Error Codes

All errors return a consistent JSON envelope matching the OpenAI error schema. Every response — success or failure — includes an X-Request-Id header. Quote it in any support email and we can pull the full trace.

Error format

{
  "error": {
    "type": "invalid_request_error",
    "message": "Human-readable description of the error",
    "code": "machine_readable_code",
    "param": "field_name"
  }
}

Status code map

StatusClassWhen you see itRetry?
400invalid_request_errorRequest body or parameters failed validation.No — fix the request.
401authentication_errorMissing, invalid, or revoked credentials.No — refresh credentials.
402quota_exceededCredit balance or a spend cap is exhausted.No — top up or raise the cap.
403permission_deniedAuthenticated, but not allowed (suspended org, model not enabled, IP blocked, etc.).No — fix the policy or pick another model.
404not_foundResource doesn't exist or isn't visible to you.No.
409conflictIdempotency or uniqueness collision (e.g. coupon already used).No — resolve the conflict.
413invalid_request_errorRequest body over the size cap: 32 MiB on /v1/chat/completions and /v1/embeddings, 10 MiB on every other route. The message states the limit; base64 attachments count at their encoded size. See 413 — request too large.No — send fewer or shorter messages and tool outputs, or shrink attachments.
422invalid_request_errorJSON parsed but fields are invalid.No — fix the request.
429rate_limit_errorPer-key RPM ceiling hit (Retry-After 1–60 s; message quotes your plan's limit), or an edge burst above 100 req/s / 400 concurrent on one key (Retry-After: 1; message Too many requests at the edge; retry after 1 second.). Same JSON shape — honour the Retry-After header either way.Yes, after the window.
499(informational)Client closed the connection mid-stream. Billed for tokens produced up to the disconnect.n/a
500internal_errorUnhandled server-side fault.Yes, with backoff.
503service_unavailableThe model is temporarily unavailable — or, with code large_request_backpressure, a burst of very large requests briefly exceeded the platform's in-flight body budget (Retry-After: 2).Yes, after Retry-After (30–60 s for a model outage).

400 — validation errors

CodeWhen
model_not_foundModel name not in your catalog. Check GET /v1/models.
model_not_supported_on_endpointModel exists but doesn't support this endpoint (e.g. embeddings model on /v1/chat/completions).
invalid_roleA message has a role other than system, user, assistant, or tool.
missing_contentA message is missing required content.
max_tokens_exceededmax_tokens exceeds the model's context window.
empty_inputEmbeddings request with an empty input.
input_too_largeEmbeddings input exceeds the model's per-call token budget.
invalid_requestGeneric validation error. Check the param field.

401 — authentication errors

CodeMeaningFix
missing_auth_headerNo Authorization header.Add Authorization: Bearer sk-... (or a dashboard session token).
invalid_api_keyAPI key not recognised.Use a valid key from the dashboard.
invalid_api_key_formatToken doesn't start with sk-.Check you didn't paste a placeholder.
key_revokedThe key was revoked.Create a new key.
key_expiredThe key passed its expiry date.Create a new key or extend the expiry.
invalid_token_typeWrong token type for this endpoint.Use the access token from login, or an API key for API calls.
token_revokedSession was ended (logout or revoke).Log in again.
user_not_found / user_disabledAccount no longer active.Contact your org owner or support.
not_a_memberYou don't belong to the selected organisation.Pick a different org in the dashboard.

402 — spending limits

402 means you need to act on billing before more traffic is accepted (unlike 429, which is temporary).

CodeWhere it firesResolution
quota_exceededOrg credit balance is zero on a priced model.Top up credits or use a model with free quota.
insufficient_balanceThis request would exceed your remaining balance.Top up, lower max_tokens, or shorten the prompt; for images, request fewer or smaller images.
spending_cap_reachedPer-key monthly spend cap hit.Raise the cap on the key or use a different key.
project_spend_cap_exceededPer-project monthly cap hit.Raise the cap under Projects → Limits.

Example response:

{
  "error": {
    "type": "quota_exceeded",
    "message": "Project monthly spend cap of 500.00 EGP exceeded.",
    "code": "project_spend_cap_exceeded"
  }
}

403 — policy / permission denied

CodeMeaning
org_suspendedThe organisation has been suspended. Contact support.
email_not_verifiedDashboard/playground use before email verification is complete.
permission_deniedYour role doesn't allow this action.
ip_not_allowedRequest came from an IP not on the key's allow-list.
key_scope_insufficientThe key doesn't have permission for this endpoint.
model_not_availableModel isn't on your plan or org allow-list.
model_sunsetModel has been retired. See the changelog.
model_not_enabled_for_projectModel isn't enabled for this project.
project_not_in_orgSelected project doesn't belong to the active organisation.

413 — request too large

The raw JSON body of one request may be at most 32 MiB (33,554,432 bytes) on POST /v1/chat/completions and POST /v1/embeddings, and 10 MiB (10,485,760 bytes) on every other route. Base64 attachments count at their encoded size (4/3 of the file). Within a body, one message holds at most 2,000,000 characters of text and 5 MB (decoded) of media, across at most 20 media parts per request — those limits answer with 422.

CodeMeaningFix
request_too_largeThe body is over the route's cap. The message quotes the declared size (when the client sent Content-Length) and the limit.Not retryable. Drop earlier turns or tool outputs, or shrink attachments. Agentic clients should compact the conversation.
{
  "error": {
    "type": "invalid_request_error",
    "message": "Request body too large: 34,000,000 bytes declared; the limit for POST /v1/chat/completions is 33,554,432 bytes (32 MiB). Send fewer or shorter messages and tool outputs, or shrink base64 attachments.",
    "code": "request_too_large",
    "request_id": "req_86By4H0S9VTH8PneVWokg"
  }
}

429 — rate limits

CodeMeaningFix
rate_limit_exceededPer-key RPM ceiling exceeded.Honour Retry-After. See Rate Limits.

500 / 503 — server errors

CodeMeaningFix
internal_errorGeneric server fault.Retry with backoff; send X-Request-Id to support if persistent.
service_unavailableService temporarily down.Retry in 30–60 s.
large_request_backpressureA burst of very large request bodies briefly exceeded the platform's in-flight body budget; your request was refused before it was read.Retry after Retry-After (2 s) — the official SDKs do this automatically.
no_healthy_backendsModel temporarily unavailable.Retry, or switch to another model from the model library.
engine_unavailableModel starting up or overloaded.Retry once.

Handling errors in Python

from openai import (
    APIError,
    AuthenticationError,
    BadRequestError,
    PermissionDeniedError,
    RateLimitError,
)
 
try:
    response = client.chat.completions.create(
        model="gpt-oss-20b",  # live id from GET /v1/models
        messages=[{"role": "user", "content": "Hello"}],
    )
except AuthenticationError as e:
    print(f"Auth failed: {e.message}")
except PermissionDeniedError as e:
    print(f"Forbidden: {e.message}")
except BadRequestError as e:
    print(f"Bad request: {e.message}")
except RateLimitError as e:
    retry_after = e.response.headers.get("Retry-After", "60")
    print(f"Rate limited; retry after {retry_after}s")
except APIError as e:
    if e.status_code == 402:
        print(f"Billing block: {e.message}")
    else:
        print(f"API error ({e.status_code}): {e.message}")

Handling errors in Node.js

try {
  const response = await client.chat.completions.create({/* ... */});
} catch (error) {
  if (error instanceof OpenAI.AuthenticationError) {
    console.error(`Auth: ${error.message}`);
  } else if (error instanceof OpenAI.PermissionDeniedError) {
    console.error(`Forbidden: ${error.message}`);
  } else if (error instanceof OpenAI.BadRequestError) {
    console.error(`Validation: ${error.message}`);
  } else if (error instanceof OpenAI.RateLimitError) {
    console.error('Rate limited');
  } else if (error.status === 402) {
    console.error(`Billing block: ${error.message}`);
  } else if (error instanceof OpenAI.InternalServerError) {
    console.error('Server error — retry');
  }
}

Getting help

PreviousRate Limits