Reference

Error codes

The HTTP statuses that come back from the fal queue and what to do with each one. Treat this as a triage sheet.

Status	Meaning	Retry	Action
400 Bad Request	Your request body failed schema validation (missing required field, wrong type, value out of range).	no	Fix the request and resubmit.
401 Unauthorized	The Authorization header was missing or the key was malformed.	no	Check FAL_KEY in the environment; rotate if in doubt.
403 Forbidden	Your key is valid but lacks access to this endpoint or has been revoked.	no	Check the fal dashboard for key status and quota.
422 Unprocessable Entity	The prompt or an input asset hit a content filter, or the model rejected the parameters as unsupported.	no	Reword the prompt, remove the offending asset, or loosen safety_tolerance if the model exposes it.
429 Too Many Requests	You exceeded your per-minute or concurrent-job limit.	yes, after backoff	Retry with exponential backoff. See /docs/rate-limits.
500 Internal Server Error	Transient failure inside fal or the underlying model.	yes, after backoff	Retry the same request after a short delay. If it fails three times, stop and open an issue with the request id.
503 Service Unavailable	The model cold-started or the region is temporarily saturated.	yes, after backoff	Retry after 2 to 5 seconds.
504 Gateway Timeout	The upstream model did not respond in time. The job may still be running on the queue.	yes	Check the status endpoint with your request id before resubmitting.

Logging

Always capture the request_id from the response. It is the only way to look up a specific job later.
Log both your own request payload and the full upstream response body (with the key redacted) on 4xx and 5xx.
On 422 content-filter rejections, store the rejected prompt for review. Do not auto-retry with the same text.

Also reading