OpenAI API Error Code Explainer
Search every OpenAI API error by status code, error code, or message text. Each entry shows the HTTP status, error type, root cause, the fix, and whether the error is retryable — so you can stop guessing whether that 429 means you need to back off or add billing credits.
How to use the OpenAI API Error Code Explainer
Type any fragment into the search box — HTTP status code, OpenAI error code string, or keywords from the error message you received. The list filters live across all three fields.
Each card shows:
- Status — the HTTP status code returned by the API.
- Code — the
error.codeorerror.typefield in the JSON response body. - Cause — why the API returns this error.
- Fix — the concrete action to take.
- Retryable — whether adding an automatic retry (with exponential back-off) will resolve it.
The most important distinction: 429 rate_limit_exceeded (retryable — slow down) vs 429 insufficient_quota (not retryable — billing problem, add credits or upgrade plan). These share the same HTTP status but require completely different responses.
OpenAI API error structure
The OpenAI API returns errors as JSON objects with three fields: error.type (the broad category), error.code (the specific code, sometimes null), and error.message (a human-readable description). The HTTP status code is a rough guide, but the error code is the authoritative signal for deciding how to handle the error in code.
The single biggest source of confusion in OpenAI error handling is the two different flavors of 429. rate_limit_exceeded means your application is sending requests too fast relative to your tier's TPM/RPM limits — backing off and retrying will work. insufficient_quota means your account has hit a billing hard limit and no number of retries will fix it; the user or operator must add credits or upgrade the plan. Many engineers spend hours adding retry logic for a 429 that is actually a billing block. Check the error code, not just the status.
Transient server-side errors (500, 503) are genuinely retryable. Honor the Retry-After header when present; otherwise use exponential back-off starting at 1 second. context_length_exceeded errors require reducing your prompt or switching to a model with a larger context window — retrying the exact same request will always fail.
Common use cases
- Debugging production 429s — quickly confirm whether you need rate-limit logic or a billing fix without reading the full API docs.
- Error handler design — identify which codes are retryable so you can build correct exponential back-off logic.
- Onboarding new API users — share this reference so engineers understand the error taxonomy before they hit production issues.
- Incident triage — during an outage, confirm in seconds whether a 503 is your problem or OpenAI's servers.
- Context window planning — understand context_length_exceeded so you can size chunks and select models proactively.
Frequently asked questions
Why does 429 mean two completely different things?
rate_limit_exceeded) and quota exhaustion (insufficient_quota). Always inspect error.code in the response body — do not make retry decisions based on the status code alone.What is the correct retry strategy for rate limit errors?
Retry-After header; if present, wait that many seconds. Otherwise use exponential back-off: 1s, 2s, 4s, 8s up to a maximum of ~60s. Add jitter (±10%) to avoid thundering-herd when many clients retry simultaneously.How do I fix context_length_exceeded?
Is a 500 server_error my fault?
How do I tell if an error is a model access or billing issue?
unsupported_country_region_territory is a geographic restriction. A 404 with model_not_found means your account tier does not have access to that model (check your organization's model access settings). insufficient_quota is a billing issue.