Errors and recovery
Introduction
Errors return an error.code. Handle the HTTP status first, then react to the specific code; do not retry every error the same way. Validation failures (400 invalid_input) also carry error.message explaining what to correct and, when one can be identified, error.field naming the offending field or header; nothing is submitted or charged when that status is returned.
| Status | Meaning | Typical codes |
|---|---|---|
| 400 | Invalid parameters or material. | invalid_input |
| 401 | Missing or invalid key. | unauthorized |
| 402 | Insufficient credits. | insufficient_credits |
| 403 | Not permitted for this source or account. | forbidden |
| 404 | Unknown source or task not owned. | not_found |
| 409 | Quote, request or idempotency conflict. | conflict |
| 429 | Concurrency or rate limit. | concurrency_limit_reached |
| 503 | Configuration or service temporarily unavailable. | — |
- A timeout, a dropped connection or a 5xx response does not prove failure.
- Read the task with the UUID you already saved; a 404 does not prove the provider never received it.
- GET requests may retry with bounded backoff; leave
pendingtasks for reconciliation.
Never blind-resubmit a billable generation with a new idempotency key after an ambiguous outcome.
PreviousRequests and responses