Build

Errors and retries

The error format, every status the API returns, what you're charged, and which errors to retry.

Error format

Errors come back in the OpenAI shape:

{
  "error": {
    "message": "invalid api key",
    "type": "auth_error",
    "code": "invalid_api_key"
  }
}

Branch on the HTTP status and code. param names the field at fault, when there is one. message is written for people and may change. An error returned by the model itself is passed through with its own status and body.

Statuses

Status	`code`	Meaning	Retry
`400`	`malformed_json`, `unknown_parameter`, `invalid_request_body`	The body isn't valid JSON, has a parameter outside the OpenAI API, or has an invalid value. `param` names the field.	No: fix the request.
`400`	`max_tokens_exceeds_model_limit`, `token_limit_exceeded`	`max_tokens` is above what the model allows.	No: lower `max_tokens`.
`400`	`endpoint_not_supported`	The model is served on a different endpoint.	No.
`401`	`invalid_api_key`, `api_key_expired`	The key is missing, wrong, revoked or expired.	No: fix the key.
`402`	`insufficient_funds`	Your balance, or the key's credit cap, can't cover the request's maximum cost.	After adding credit, or with a smaller `max_tokens`.
`403`	`model_not_allowed`	The key isn't allowed to use this model.	No.
`404`	`model_not_found`	Unknown model id. It's checked before the key, so a typo answers `404` whatever the key.	No: check the catalogue.
`409`	`duplicate_idempotency_key`	A request with this `Idempotency-Key` already ran, or is still running.	No.
`413`	`request_too_large`	The request is over 2 MB.	No.
`429`	`rate_limited_key`, `rate_limited_org`, `rate_limited_model`, `upstream_rate_limited`	Too many requests for the key or organisation, or the model is at capacity.	Yes, after `Retry-After`.
`502`, `503`		The model is temporarily unavailable.	Yes, with backoff.

What you're charged for

Requests that fail are never charged. A stream that ends early is charged for the output it delivered before it ended; its row in the request logs is marked as estimated.

Retrying

Retry 429 and 5xx. Wait for Retry-After when it's present; otherwise back off exponentially with jitter (for example 0.5 s, 1 s, 2 s, then stop).
Don't retry other 4xx. They need a change to the request, the key or your balance, and the OpenAI SDKs won't retry them automatically.
Make retries safe. A retried request that succeeds runs, and is charged, twice. Send an Idempotency-Key header to prevent that; see Chat completions.
Don't retry a stream you've partly received. Treat it as done.

How a request ended

Your request logs record how each request ended, in termination_reason:

Value	Meaning
`success`	Completed.
`client_disconnect`	Your client closed the connection before the end.
`proxy_guillotine`	The request reached the five-minute limit.
`upstream_stream_aborted`	The model stopped the stream midway.

A refused request records its error code instead, for example insufficient_funds.

Account API errors

The Account API uses its own error format; see Account API.

Something unclear or wrong on this page? Tell us. Machine-readable copies: llms.txt.