Skip to navigation

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:

{
"type": "error",
"error": {
"type": "error_type",
"message": "Human-readable error message"
}
}

The same { type, message } shape surfaces in two places:

  • HTTP errors: in the response body of a failed POST or GET request.
  • Job failures: in the error field of a job with status: "failed".

HTTP errors

StatusError typeDescription
400invalid_request_errorInvalid request parameters.
401authentication_errorAPI key missing or invalid.
402insufficient_funds_errorNot enough credits to request an upload URL from POST /v1/upload. See Pricing.
404not_found_errorJob doesn’t exist or has expired.
413request_too_large_errorRequest body exceeds 32 MB. See Input Formats.
429rate_limit_errorQueue limit exceeded. See Concurrency and Queue Limits. Retryable
500api_errorUnexpected server error. Retryable

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:

{
"id": "a1b2c3d4e5f67890abcdef1234567890",
"status": "failed",
"created_at": "2026-01-15T10:00:00.000Z",
"completed_at": "2026-01-15T10:02:30.000Z",
"error": {
"type": "content_filtered_error",
"message": "Content filtered due to policy restrictions"
}
}

A failed job can’t be resumed; to retry, submit the request again.

Error typeDescription
invalid_request_errorThe input failed checks that run with the job, for example media that can’t be decoded or exceeds a limit. message has the details.
insufficient_funds_errorNot enough credits to run the job. See Pricing.
content_filtered_errorContent rejected by safety filters.
api_errorUnexpected server error. Retryable
service_unavailable_errorAn input file couldn’t be fetched from Cloud Storage. Retryable
overloaded_errorNo capacity to run the job in time. Retryable
request_timeout_errorThe request exceeded its processing time limit. Retryable

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.