Errors
Telling them apart#
An HTTP error means the request never became a task. You get a 4xx or 5xx status immediately, and nothing was charged.
A task failure means the request was accepted with a 200 and a task ID, then failed during processing. You discover it by retrieving the task and reading failureCode.
The two rules worth memorising#
429 means the daily cap, not requests per minute. There is no per-minute limit — excess concurrent work is queued as THROTTLED. A persistent 429 means tiering up, not backing off harder.
SAFETY.INPUT.* is the one failure that does not refund credits. Never retry it: you will be charged again for the same rejection.
Related#
- Go-live checklist — testing failure paths before launch
- Usage tiers — the limits behind most
429s - Inputs — the constraints behind most
400s
Handle failures before users see them
The go-live checklist walks every failure path with the code to handle it.