[plainprogrammer]

After a 429 with no usable Retry-After, the Scryfall client no longer asks again inside the 30 seconds Scryfall says a 429 limits access for. The call ends at once and the job comes back 45 seconds later.

Closes #81

Stacked on #85 (the fix for #79 and #80): both edit spec 011's version history and the same CLAUDE.md paragraph, so this branch merges that one. Merge #85 first.

What changed

• A 429 with no usable Retry-After ends the call at once with Catalog::Sources::RateLimitedError carrying no wait, on any attempt, for get_json and fetch_image. Before, the client retried after 1 and 2 seconds, so all three attempts landed inside the window. "No usable" covers an absent, empty, whitespace-only, negative, non-numeric or past-dated header, and now a zero: obeying Retry-After: 0 allowed three requests in about 0.2 seconds.
• The job's floor is 45 seconds (Catalog::RateLimitRetry::SHORTEST_WAIT, was 30). The retry is scheduled from when the error is handled, so at 30 the next request cleared the window only by the dispatcher's polling delay.
• Unchanged: a 5xx without the header still retries after 1 and 2 seconds; a usable Retry-After of 1 to 30 seconds is slept exactly; a longer one ends the call carrying the wait; the worst-case sleep per call stays 60 seconds, so the art build's 2-minute rule holds.
• Specs 002 and 011 (both 1.3.0), CLAUDE.md and the comments in client.rb, art_build.rb and art/build.rb state the new figures.

What Scryfall's pages say

Their rate-limits, API overview and errors pages state that a 429 limits access for 30 seconds, that continuing may lead to a ban, and that *.scryfall.io has no rate limits. None mentions Retry-After. What a real 429 carries is still unobserved (no rate limit was provoked to find out), so both cases are specified.

Decisions for you

1. Raise at once, not wait 30 seconds in the call. No worker sleeps and the client has one rule for every caller. The cost is on the art build: one header-less 429 from the image host stops the build and costs one of the job's 3 rate-limit retries, where it used to cost about 3 seconds. The review agreed with the choice and asked for Rate-limit retries count over a job's whole life, so a long build can run out #86 to cover the retry budget.
2. 45 seconds for the floor. The review suggested 45 to 60.

Verification

• bin/ci: passed, 1405 examples, 0 failures, 1 pending (the art agreement spec, unrelated).
• New client, refresh-job, build-job, build and admin-page examples, each seen failing first.
• One independent read-only review (Opus): no must-fix. With the old back-off patched back in, 25 examples fail. It checked the quotes against the fetched Scryfall pages. Its follow-ups (the zero header, the floor's margin, the CLAUDE.md sentence, one admin-page example, one spec 011 row) are the last five commits.
• Not verified: a real 429 from Scryfall.

Known limits and follow-ups

• The 3 rate-limit retries count over a job's whole life, so a long first build can run out: Rate-limit retries count over a job's whole life, so a long build can run out #86.
• A Retry-After of 1 to 29 seconds is still obeyed, although the documented limit is 30. It is Scryfall's own number.
• A waiting job holds no lock, so a second refresh can ask early: A second refresh can ask the source while another waits out a rate limit #78. No override while a retry waits: No way to start or cancel while a rate-limited job waits to retry #77.
• docs/roadmap.md still lists Scryfall client retries inside the 30 seconds a 429 limits access for #81 as open.

🤖 Generated with Claude Code