Concepts

Errors

Reference codes and how to handle them.

Error shape

Errors return a non-2xx status and a consistent envelope with a type, machine-readable code and human message.

{
  "error": {
    "type": "invalid_request_error",
    "code": "insufficient_credits",
    "message": "Not enough credits (need 24)"
  }
}

Field	Type	Description
`400`	invalid_request_error	Malformed request or unknown model/action.
`401`	authentication_error	Missing or invalid API key.
`402`	invalid_request_error	insufficient_credits — top up to continue.
`404`	invalid_request_error	Resource not found.
`422`	invalid_request_error	invalid_params — a param failed validation.
`429`	rate_limit_error	Too many requests or concurrent jobs for your plan.
`500`	api_error	Something went wrong on our end — safe to retry.

Treat 429 and 500 as retryable with backoff. 402 and 422 are terminal — fix the input or balance before retrying.