OpenAI API errors explained: codes, causes and fixes

Use OpenAI’s structured error code to separate a request bug from an account or service condition. Preserve a redacted reproduction so the corrective action can be tested rather than guessed.

Error format at OpenAI

The error reference documents status codes, more specific error codes and SDK exception categories. A broad insufficient_quota type may still need its specific code inspected. Official documentation.

Preserve the response’s specific code and the stage where the failure occurred. Distinguish a rejected request from a connection failure, an interrupted stream and an exception in your own result parser. A useful diagnostic record identifies the selected model and endpoint without exposing the API key or full customer prompt.

Keep a small redacted fixture that reproduces the same condition. If a production request contains private documents, replace them with safe material that preserves the relevant input shape. Verify that the replacement still fails in the same way before sharing it. This gives a reviewer useful evidence without making access to sensitive customer data a prerequisite for debugging.

Error code table

Status	Documented code or category	What to inspect	Action
401	Authentication	Active credential and project	Repair access configuration.
429	`credit_balance_exhausted`	Account credit	Resolve the account condition.
429	`slow_down`	Traffic ramp	Reduce and gradually resume traffic.
429	`project_spend_limit_exceeded`	Project spending control	Review the configured limit.
429	`organization_usage_limit_exceeded`	Approved usage	Use the provider’s increase process.
503	`server_is_overloaded`	Temporary model capacity	Follow retry timing and status evidence.

The codes come from the provider’s error reference; the investigation wording is editorial guidance. Official documentation.

Use the table to select an investigation, then read the actual message and code. A broad label can hide whether the project has exhausted credit, reached an enforced spending control or sent traffic too quickly. Keep those conditions distinct in monitoring so the account owner receives an actionable alert.

Avoid automatically exposing the provider’s entire error body to the application’s end user. Preserve detailed diagnostics in the appropriate protected record and present a concise product message. The operator should know where to inspect the relevant project or account setting; the end user should not be asked to repair organization billing or provide an API key.

Authentication errors

Compare the deployed secret with the project-key configuration. Check the failing process’s environment rather than re-creating credentials blindly.

Compare the failing process with the smallest known-good Responses request. Inspect the selected project, secret version and endpoint. A local success does not establish that the deployed worker loaded the same configuration. If the application recently rotated a credential, check each consumer before creating more replacements.

Keep the credential identity in the operating record without its value. This helps the project owner determine which key was intended and whether it has expired or been revoked. If exposure is suspected, perform a controlled rotation and inspect usage rather than pasting the key into a support request as evidence.

Rate and quota errors

Use the OpenAI limits guide to separate pace, credit and enforcement. A billing condition should not become an endless retry loop.

Read the specific code before selecting recovery. Pacing can address a transient traffic condition, while a credit or configured-spend boundary requires an account decision. Do not keep retrying a billing condition as though waiting a little longer will repair it.

Inspect queue age and arrival pattern when rejected requests increase. A deployment can release accumulated work or multiply retries unexpectedly. Pause the ramp, sample real responses and resume with a deliberate schedule. Preserve unfinished task identities so a pause does not turn into either lost work or accidental duplicate submissions.

Request validation errors

Reduce the payload to the required fields for its endpoint. Add optional output formatting, media and tools independently so each change has an observable effect.

Reduce the request to the basic schema for its endpoint. Add output-format options, media and tools independently, recording which addition changes the result. If the request came from another provider’s example, verify each field against the OpenAI interface rather than assuming compatibility from a shared SDK.

Keep a passing baseline in the project alongside the application-specific example. This lets a maintainer distinguish access and library problems from a malformed feature request. Do not delete evidence by continually editing the only failing script; save meaningful variations with the observed outcome.

Model and context errors

Check the exact API identifier and supported features in the model catalog. Official documentation.

Keep an application record of the input material and response allowance without logging sensitive prompt contents.

Inspect the exact model string sent at runtime. An environment override or scheduled command can differ from the value visible in an editor. Confirm both catalog spelling and account access before changing the request’s substantive content.

If input size is the issue, identify the evidence the task actually needs before dropping arbitrary material. Retest the answer after changing context selection. If you switch models to accommodate the request, rerun the application’s quality and output-handling checks. A newly accepted request does not by itself prove that the original task is still being completed correctly.

Server errors and status

Open the official status source from the OpenAI hub. Preserve the failed request identifier and the bounded retry history when investigating a persistent incident.

Use the AI API cost calculator to turn the model and workload you are considering into an estimate.

Record the time window, affected model and application environments when investigating a persistent service failure. Compare provider status with your own request evidence. An incident notice can support an explanation, but it does not establish that every unrelated application bug has the same cause.

Escalate with a concise reproduction, redacted response and the recovery behavior already attempted. State what succeeds as well as what fails. This makes a model-specific condition, deployment-network issue or request-shape problem easier to distinguish without giving another person access to customer prompts or credentials.

Last verified 12 Sep 2026 · Source ↗

Frequently asked questions

Should every rejected request be retried?

No. Billing and configured-limit errors need their account condition resolved. Official documentation.

Why inspect error.code as well as error.type?

The specific code can distinguish credit, spending and usage problems inside a broader category. Official documentation.

Can an old SDK affect diagnosis?

Record the installed SDK version and reproduce with the request interface documented for your application.

What belongs in a correction report?

The endpoint, exact model identifier, redacted error and the smallest request that reproduces it.

What should never be included?

An API secret, full sensitive prompt, or unrelated account information.

Sources

Last verified 12 Sep 2026 · Source ↗