Skip to content
OneAPIDocs
ModelsOpen console

API reference

Errors

Branch on the code field, not the message. Codes are stable; messages are written for people and can change.

Error envelopes

An error comes back in the format of the path you called, so an SDK raises its usual exception type. Both envelopes carry the same message; only the OpenAI one has code.

Chat Completions and Responses

402 Payment Required
{
  "error": {
    "type": "invalid_request_error",
    "code": "insufficient_credit",
    "message": "Insufficient credit. Top up to continue.",
    "param": null
  }
}

Messages

402 Payment Required
{
  "type": "error",
  "error": {
    "type": "permission_error",
    "message": "Insufficient credit. Top up to continue."
  }
}

On /v1/messages, branch on the status and error.type. Some errors add a details object with machine-readable fields, such as the plan window and its reset time.

Codes

Your request

Fix the request before sending it again. Retrying unchanged gets the same answer.

StatusCodeMeaningWhat to do
400invalid_requestThe body is not valid JSON, has no model field, or does not fit this path's format.Read the message; it names the problem.
400unsupported_parameterA field cannot be converted to the format the model is served in.Remove the named field or pick another model.
400web_search_unavailableThe request asked for web search (:online or plugins) while it is switched off.Retry later, or send the request without :online.
401unauthorizedThe key is missing, wrong, disabled, revoked or expired.Check the key and the header it is sent in.
403unknown_modelThe key has an allowed-models list and this model is not on it.Use an allowed model or edit the key.
403plan_model_not_allowedYour active plan does not include this model.Use a model the plan covers.
403content_refusedThe model provider declined the request under its usage policy.Change the prompt. Sending it again unchanged gets the same answer.
403guard_pausedThis account drew repeated policy refusals on this model and is paused on it for a while.Wait for Retry-After; other models keep working.
404unknown_modelNo routed model has this ID.Check the ID against GET /v1/models.
404provider_disabledThe model exists but is switched off for now.Pick another model or try later.

Your account and limits

The request was valid; something about the account or its limits refused it.

StatusCodeMeaningWhat to do
402insufficient_creditThe balance cannot cover this request.Top up on the Billing page.
402account_frozenThe account is frozen.Contact support.
429quota_exceededThis key reached its spend cap for the period.Wait for Retry-After, or raise the cap.
429rate_limit_exceededToo many requests per minute.Wait for Retry-After, then retry.
429concurrency_limit_exceededToo many requests running at once.Retry after one of them finishes.
429extra_usage_disabledA usage window of your plan is used up.Wait for details.reset_at.

The gateway or the provider

Not caused by your request. Retrying with backoff is the right response.

StatusCodeMeaningWhat to do
500internal_errorThe gateway failed.Retry. Report the X-Request-Id if it repeats.
502upstream_errorThe provider returned an error or could not be reached.Retry with backoff.
502upstream_auth_errorThe provider refused the gateway's own credentials.Retry later; this is on our side.
502upstream_rate_limitedThe provider is rate limiting the gateway.Retry with backoff.
502invalid_upstream_usageThe provider's answer had no usable token counts.Retry.
503provider_no_keyThe model has no working provider credential right now.Pick another model or retry later.
503rate_limit_unavailableThe rate limiter is down, so the gateway refuses rather than guess.Retry shortly.
504upstream_timeoutThe provider did not answer in time.Retry, or shorten the request.

Headers to read

HeaderWhenMeaning
X-Request-IdEvery responseThe ID of this request. Quote it to support.
Retry-AfterSome 429sSeconds until a retry can succeed.
X-RateLimit-Limit-RequestsKeys with a per-minute limitRequests allowed per window.
X-RateLimit-Remaining-RequestsKeys with a per-minute limitRequests left in this window.
X-RateLimit-Reset-RequestsKeys with a per-minute limitTime until the window resets, such as 12s.

Retrying

Retry 429, 500, 502, 503 and 504 with exponential backoff, and honour Retry-After when it is present. Do not retry other 4xx codes without changing the request or the account. The official OpenAI and Anthropic SDKs already retry the retryable statuses.