Errors

Errors use the OpenAI error envelope, so existing SDKs surface them cleanly. The HTTP status tells you the category; the body gives a machine-readable code.

Error shape#

json

{
  "error": {
    "message": "Invalid or revoked API key.",
    "type": "invalid_request_error",
    "code": "invalid_api_key",
    "param": null
  }
}

Status codes#

Field	Type	Description
`400`	invalid_request_error	Missing or malformed parameters (e.g. no model or prompt).
`401`	invalid_request_error	Missing, invalid, or revoked API key.
`402`	insufficient_quota	Not enough credits — top up or upgrade.
`403`	invalid_request_error	Key not authorized for this scope (insufficient_scope).
`404`	invalid_request_error	Unknown model, job, or resource.
`429`	rate_limit_error	Rate limit exceeded — see the Retry-After header.
`502`	api_error	The upstream model provider returned an error.

Common codes#

Field	Type	Description
`missing_api_key`	401	No Authorization: Bearer header was sent.
`invalid_api_key`	401	The key is unknown, revoked, or expired.
`insufficient_scope`	403	The key lacks the scope for this endpoint.
`insufficient_credits`	402	Your credit balance is too low for the request.
`model_not_found`	404	The model id doesn't exist or isn't allowed for this key.
`rate_limit_exceeded`	429	Too many requests in the current window.

Handling errors#

Retry 429 after the Retry-After header, and treat 502 as transient (retry with backoff). 400, 401, 403, and 404 are client errors — fix the request rather than retrying.