For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Primary navigation

Suggested

Go live

Performance and quality

Cost and throughput

Safety and governance

Infrastructure and access

Operations

API Dashboard
Try ChatGPT

Error codes

Explore API error codes and solutions.

This guide includes an overview on error codes you might see from both the API and our official Python library. Each error code mentioned in the overview has a dedicated section with further guidance.

API errors

CodeOverview
400 - Invalid service_tier argumentCause: The requested or resolved service tier is not allowed for the project.
Solution: Set service_tier to a tier allowed for the project, or update the allowed service tiers in project settings.
401 - Invalid AuthenticationCause: Invalid Authentication
Solution: Ensure the correct API key and requesting organization are being used.
401 - Incorrect API key providedCause: The requesting API key is not correct.
Solution: Ensure the API key used is correct, clear your browser cache, or generate a new one.
401 - You must be a member of an organization to use the APICause: Your account is not part of an organization.
Solution: Contact us to get added to a new organization or ask your organization manager to invite you to an organization.
401 - IP not authorizedCause: Your request IP does not match the configured IP allowlist for your project or organization.
Solution: Send the request from the correct IP, or update your IP allowlist settings.
403 - Country, region, or territory not supportedCause: You are accessing the API from an unsupported country, region, or territory.
Solution: Please see this page for more information.
429 - Credit balance exhaustedCode: credit_balance_exhausted
Cause: Your organization has no prepaid credits remaining.
Solution: Add credits to continue using the API.
429 - Rate limit reached for requestsCause: You are sending requests too quickly.
Solution: Pace your requests and follow the Retry-After header when it’s present. Read the Rate limit guide.
429 - Slow downType: rate_limit_error
Code: slow_down
Cause: Your request rate increased too quickly.
Solution: Follow the Retry-After header when it’s present, reduce your request rate, and increase it gradually.
429 - Organization spend limit reachedCode: organization_spend_limit_exceeded
Cause: Your organization reached its enforced spend limit.
Solution: Increase or remove your organization spend limit.
429 - Project spend limit reachedCode: project_spend_limit_exceeded
Cause: Your project reached its enforced spend limit.
Solution: Increase or remove the spend limit in your project settings.
429 - Organization usage limit reachedCode: organization_usage_limit_exceeded
Cause: Your organization reached its OpenAI-assigned usage limit.
Solution: Request a higher approved usage limit or contact support.
500 - The server had an error while processing your requestCause: Issue on our servers.
Solution: Retry your request after a brief wait and contact us if the issue persists. Check the status page.
503 - Model temporarily overloadedType: service_unavailable_error
Code: server_is_overloaded
Cause: The requested model is temporarily overloaded.
Solution: Follow the Retry-After header when it’s present, then retry your request.

For billing-related errors, inspect error.code to identify the specific cause. The broader error.type can still be insufficient_quota.

Retrying billing, spend, or quota errors won’t restore API access. Update the relevant credits or limits before sending another request.

WebSocket mode errors

If you are using the Responses API WebSocket mode, you may see these additional errors:

  • previous_response_not_found: The previous_response_id cannot be resolved from available state. Retry with full input context and previous_response_id set to null.
  • websocket_connection_limit_reached: The connection hit the 60-minute limit. Open a new WebSocket connection and continue.

Python library error types

Python raises RateLimitError for 429 responses and InternalServerError for 503 responses. If your handler previously caught only one of these classes for throttling and overload, handle both and inspect error.code. Video overload, for example, now returns 503 where it previously returned 429. See migration guidance for the endpoint-specific changes.

TypeOverview
APIConnectionErrorCause: Issue connecting to our services.
Solution: Check your network settings, proxy configuration, SSL certificates, or firewall rules.
APITimeoutErrorCause: Request timed out.
Solution: Retry your request after a brief wait and contact us if the issue persists.
AuthenticationErrorCause: Your API key or token was invalid, expired, or revoked.
Solution: Check your API key or token and make sure it is correct and active. You may need to generate a new one from your account dashboard.
BadRequestErrorCause: Your request was malformed or missing some required parameters, such as a token or an input.
Solution: The error message should advise you on the specific error made. Check the documentation for the specific API method you are calling and make sure you are sending valid and complete parameters. You may also need to check the encoding, format, or size of your request data.
ConflictErrorCause: The resource was updated by another request.
Solution: Try to update the resource again and ensure no other requests are trying to update it.
InternalServerErrorCause: Issue on our side.
Solution: Retry your request after a brief wait and contact us if the issue persists.
NotFoundErrorCause: Requested resource does not exist.
Solution: Ensure you are the correct resource identifier.
PermissionDeniedErrorCause: You don’t have access to the requested resource.
Solution: Ensure you are using the correct API key, organization ID, and resource ID.
RateLimitErrorCause: You have hit your assigned rate limit or increased traffic too quickly.
Solution: Pace your requests and follow Retry-After when it’s present, subject to your retry limits. Read more in our Rate limit guide.
UnprocessableEntityErrorCause: Unable to process the request despite the format being correct.
Solution: Please try the request again.

Persistent errors

If the issue persists, contact our support team via chat and provide them with the following information:

  • The model you were using
  • The error message and code you received
  • The request data and headers you sent
  • The timestamp and timezone of your request
  • Any other relevant details that may help us diagnose the issue

Our support team will investigate the issue and get back to you as soon as possible. Note that our support queue times may be long due to high demand. You can also post in our Community Forum but be sure to omit any sensitive information.

Handling errors

We advise you to programmatically handle errors returned by the API. To do so, you may want to use a code snippet like below:

import OpenAI from "openai";

const client = new OpenAI();

try {
  const response = await client.responses.create({
    model: "gpt-6-astra",
    input: "Hello world",
  });
  console.log(response.output_text);
} catch (error) {
  if (error instanceof OpenAI.APIConnectionError) {
    console.error("Failed to connect to the OpenAI API:", error.message);
  } else if (error instanceof OpenAI.RateLimitError) {
    console.error("OpenAI API request exceeded its rate limit:", error.message);
  } else if (error instanceof OpenAI.APIError) {
    console.error("OpenAI API returned an error:", error.status, error.message);
  } else {
    throw error;
  }
}