[plainprogrammer]

The Scryfall client never waits longer than 30 seconds for a Retry-After. When the source asks for more, the call ends with a rate-limit error and the job comes back when the source asked, instead of a worker sleeping for as long as the header says.

Closes #74

Stacked on #75 (the fix for #73): the two conflict in app/models/mtg/art/build.rb and spec 011, so this branch merges that one. Merge #75 first; this PR's diff is against its branch.

What changed

• The bound. MTG::Scryfall::Client::MAX_BACK_OFF is 30 seconds per wait, the time Scryfall's rate-limits page says a 429 limits access for. One call sleeps at most 60 seconds (two waits between three attempts). A longer ask ends the call at once, with no sleep and no further request, raising Catalog::Sources::RateLimitedError (a TransientError) that carries the wait asked for.
• Reading Retry-After. Whole seconds or an HTTP date, nothing else. The old Integer() parse had live bugs: -5 reached sleep and raised ArgumentError, 0x1F was waited as 31 seconds, and an HTTP date was ignored. Anything unusable falls back to 1 s, then 2 s, as before.
• No wait after the last attempt. get_json slept after its third 429 and then raised.
• The art build stops on a rate limit rather than counting a failed image. With the cap alone it would have sent one request per remaining image, 100 ms apart, to a host asking it to stay away, and recorded each as failed. Fetched images stay cached, so the next build carries on. A 404, a network error or a 5xx to the last attempt is still one failed image.
• Both jobs come back when asked (Catalog::RateLimitRetry, in Catalog::RefreshJob and MTG::Art::BuildJob): after the wait the source asked for, 30 seconds at least. A wait over 1 hour isn't scheduled, and a job gets at most 3 such retries; beyond either the job fails and shows under Failed. Without this the refresh retried at about 3 s and 21 s and then failed for good, where main slept and succeeded (found by the first review).
• Specs 002 and 011 (both 1.2.0), spec 015 (1.2.4, the art build's worst-case quiet time with the cap) and CLAUDE.md match.

Decisions for you

1. The bounds on the job's retry: a 1-hour ceiling and 3 retries per job. Both are our numbers, derived from nothing.
2. Stopping the art build is wider than the issue's text. Both reviews judged it necessary once the wait is capped.

What the admin page shows while a job waits

• Refresh: "Queued to retry. The last run failed while downloading: …" with a "Retrying at" fact. Never interrupted or stalled: the run is closed as failed before the retry is scheduled.
• Art build: plain "Queued.", with no reason and no retry time; the reason is on the failed run until the retry starts.

Verification

• bin/ci on 7d843b9 (merged with fix(admin): show a crashed art build as interrupted at once #75's branch): passed. RSpec 1347 examples, 0 failures, 1 pending (the art agreement spec, unrelated).
• New examples failed before their code, with the exceptions the commits record (the job examples that pin "leave it alone" were checked against a temporary mutation).
• Two independent read-only reviews (Opus). The first found the two job defects above, now fixed. The second ran a probe against real Solid Queue rows: the retry count survives the round trip, a job beyond the bounds gets a failed execution, the refresh's lock is released while a retry waits, and the handler takes precedence over the generic retry_on only when included after it (documented in the job, and the refresh examples catch a reorder).
• Not verified: a real 429 from Scryfall. Their page doesn't say whether one carries Retry-After.

Known limits and follow-ups

• A second refresh can ask early. The waiting job holds no lock, so the weekly job or catalog:refresh starts another refresh that asks at once. "No sooner than asked" holds per job.
• No override while a retry waits. "Refresh now" and "Build art index" are refused while a retry is scheduled, and the jobs page discards only failed jobs: up to about 3 hours in the worst case.
• The 3 retries are per job lifetime. A multi-hour first build fails on its fourth rate limit even when they are hours apart. Scryfall says *.scryfall.io, the image host, has no rate limits.
• The art build's panel hides the reason while its retry waits, unlike the refresh's.
• Without a Retry-After, the client's in-call retries are still 1 s and 2 s, inside Scryfall's 30 seconds; only the job's return is floored at 30 s.
• HTTP-date values are measured against the local clock.
• Spec 011's Reliability line says the build job retries transient errors; it retries a busy database and a rate limit.
• docs/roadmap.md doesn't list Scryfall client sleeps for Retry-After with no upper bound #74 yet.

🤖 Generated with Claude Code