Error Handling
API error responses and status codes
Every error has a type you can branch on in code and a human-readable message. This page lists each type, where it can appear, and which ones are safe to retry.
Error response format
Errors use this structure:
The same { type, message } shape surfaces in two places:
- HTTP errors: in the response body of a failed
POSTorGETrequest. - Job failures: in the
errorfield of a job withstatus: "failed".
HTTP errors
Job failures
If a job fails after you submit it, polling it still returns 200. The job’s status is "failed", and its error field says why:
A failed job can’t be resumed; to retry, submit the request again.
Retry guidance
For retryable errors, use exponential backoff with jitter — a random delay of up to 50% of your backoff interval prevents thundering-herd retries. On 429, honor the Retry-After header if present.