Error Handling

API error responses and status codes

Error response format

Errors use this structure:

1{
2  "type": "error",
3  "error": {
4    "type": "error_type",
5    "message": "Human-readable error message"
6  }
7}

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

  • V1 (sync): in the response body when the request fails.
  • V2 (async), submit: in the response body when the request fails.
  • V2 (async), job failure: in the error field of a status payload with status: "failed". See Async Jobs for the full shape.

Error types

StatusError typeRetry?What it means
400invalid_request_errorNoInvalid request parameters.
401authentication_errorNoAPI key missing or invalid.
402insufficient_funds_errorNoNot enough credits. See Pricing.
404not_found_errorNoJob doesn’t exist or has expired.
422content_filtered_errorNoContent rejected by safety filters.
429rate_limit_error, concurrency_limit_errorYesToo many requests or concurrent jobs. See Rate Limits.
500api_errorYesUnexpected server error.
503service_unavailableYesService temporarily unavailable.
529overloaded_errorYesAPI temporarily overloaded. Retry after a short delay.

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.