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
{
"error": {
"type": "invalid_request_error",
"code": "insufficient_credit",
"message": "Insufficient credit. Top up to continue.",
"param": null
}
}Messages
{
"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.
| Status | Code | Meaning | What to do |
|---|---|---|---|
400 | invalid_request | The body is not valid JSON, has no model field, or does not fit this path's format. | Read the message; it names the problem. |
400 | unsupported_parameter | A field cannot be converted to the format the model is served in. | Remove the named field or pick another model. |
400 | web_search_unavailable | The request asked for web search (:online or plugins) while it is switched off. | Retry later, or send the request without :online. |
401 | unauthorized | The key is missing, wrong, disabled, revoked or expired. | Check the key and the header it is sent in. |
403 | unknown_model | The key has an allowed-models list and this model is not on it. | Use an allowed model or edit the key. |
403 | plan_model_not_allowed | Your active plan does not include this model. | Use a model the plan covers. |
403 | content_refused | The model provider declined the request under its usage policy. | Change the prompt. Sending it again unchanged gets the same answer. |
403 | guard_paused | This account drew repeated policy refusals on this model and is paused on it for a while. | Wait for Retry-After; other models keep working. |
404 | unknown_model | No routed model has this ID. | Check the ID against GET /v1/models. |
404 | provider_disabled | The 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.
| Status | Code | Meaning | What to do |
|---|---|---|---|
402 | insufficient_credit | The balance cannot cover this request. | Top up on the Billing page. |
402 | account_frozen | The account is frozen. | Contact support. |
429 | quota_exceeded | This key reached its spend cap for the period. | Wait for Retry-After, or raise the cap. |
429 | rate_limit_exceeded | Too many requests per minute. | Wait for Retry-After, then retry. |
429 | concurrency_limit_exceeded | Too many requests running at once. | Retry after one of them finishes. |
429 | extra_usage_disabled | A 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.
| Status | Code | Meaning | What to do |
|---|---|---|---|
500 | internal_error | The gateway failed. | Retry. Report the X-Request-Id if it repeats. |
502 | upstream_error | The provider returned an error or could not be reached. | Retry with backoff. |
502 | upstream_auth_error | The provider refused the gateway's own credentials. | Retry later; this is on our side. |
502 | upstream_rate_limited | The provider is rate limiting the gateway. | Retry with backoff. |
502 | invalid_upstream_usage | The provider's answer had no usable token counts. | Retry. |
503 | provider_no_key | The model has no working provider credential right now. | Pick another model or retry later. |
503 | rate_limit_unavailable | The rate limiter is down, so the gateway refuses rather than guess. | Retry shortly. |
504 | upstream_timeout | The provider did not answer in time. | Retry, or shorten the request. |
Headers to read
| Header | When | Meaning |
|---|---|---|
X-Request-Id | Every response | The ID of this request. Quote it to support. |
Retry-After | Some 429s | Seconds until a retry can succeed. |
X-RateLimit-Limit-Requests | Keys with a per-minute limit | Requests allowed per window. |
X-RateLimit-Remaining-Requests | Keys with a per-minute limit | Requests left in this window. |
X-RateLimit-Reset-Requests | Keys with a per-minute limit | Time 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.