Error handling

Errors return a non-2xx status and a consistent JSON body. Handle the status and the error.type field.

Format#

{
  "error": {
    "type": "invalid_request",
    "message": "Request body failed validation.",
    "details": [ { "path": "duration", "message": "..." } ]
  }
}

Codes#

Status	type	When it happens
401	missing_authorization	Authorization header is missing.
401	invalid_api_key	Key is invalid or revoked.
400	invalid_request	Body failed validation — see error.details.
402	insufficient_balance	Not enough balance. Add credits in Billing.
402	paid_balance_required	You only have test (promo) credit, which the API can't use. Add paid balance. (Test credit works in the playground.)
404	model_not_found	The id in `model` doesn't exist.
404	job_not_found	Job doesn't exist or has expired.
502	generation_unavailable	Transient service failure — retry.

Best practices#

Retry with backoff on 502. On 400, inspect error.details to know which field to fix. On 402, send the user to Billing.