x-fal-needs-retry header: what Sume uses to signal a retry

fal puts an X-Fal-Needs-Retry header on errors so a client knows whether to retry. The Sume pages I read describe no such header; a Sume client reads the error category and code, honors retry-after on 429, and reuses the same Idempotency-Key.

Sume details come from Errors and credits, Generation admission and Authentication, read 2026-10-01.

What does fal say the header means?

The fal errors page lists X-Fal-Needs-Retry among required headers and tells machine clients to check it for retry decisions. The concurrency page adds that a 429 with type concurrent_requests_limit carries X-Fal-needs-retry: 1 and should be retried with exponential backoff.

Which Sume signal tells me to retry?

Two signals together. First, the category: queue means retry later with the same idempotency key. Second, for 429 the code: queue_full means the workspace has no remaining accepted generation capacity, so wait for jobs to finish or cancel queued jobs, then retry with the same idempotency key. rate_limited means request volume passed an abuse-protection limit, so back off using retry-after when present.

What about rate-limit headers?

The authentication docs say to read ratelimit-remaining rather than counting requests yourself, and to back off on retry-after, which is sent on 429. Do not retry unsafe submit requests without an Idempotency-Key.

How do I translate a fal retry loop?

Replace if header == needs-retry with a switch on category and code. Retry queue_full only after capacity frees, sleep for retry-after on rate_limited, and keep one idempotency key per intended generation. For fal's concurrency model itself, see fal AI API rate limit and concurrency.