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

Code	Overview
401 - Invalid Authentication	Cause: Invalid Authentication. Solution: Ensure the correct API key and requesting organization are being used.
401 - Incorrect API key provided	Cause: 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 API	Cause: 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 authorized	Cause: 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 supported	Cause: You are accessing the API from an unsupported country, region, or territory. Solution: Please see this page for more information.
429 - Rate limit reached for requests	Cause: You are sending requests too quickly. Solution: Pace your requests. Read the Rate limit guide.
429 - You exceeded your current quota, please check your plan and billing details	Cause: You have run out of credits or hit your maximum monthly spend. Solution: Buy more credits or learn how to increase your limits.
500 - The server had an error while processing your request	Cause: Issue on our servers. Solution: Retry your request after a brief wait and contact us if the issue persists. Check the status page.
503 - The engine is currently overloaded, please try again later	Cause: Our servers are experiencing high traffic. Solution: Please retry your requests after a brief wait.
503 - Slow Down	Cause: A sudden increase in your request rate is impacting service reliability. Solution: Please reduce your request rate to its original level, maintain a consistent rate for at least 15 minutes, and then gradually increase it.

Python library error types

Type	Overview
APIConnectionError	Cause: Issue connecting to our services. Solution: Check your network settings, proxy configuration, SSL certificates, or firewall rules.
APITimeoutError	Cause: Request timed out. Solution: Retry your request after a brief wait and contact us if the issue persists.
AuthenticationError	Cause: 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.
BadRequestError	Cause: 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.
ConflictError	Cause: The resource was updated by another request. Solution: Try to update the resource again and ensure no other requests are trying to update it.
InternalServerError	Cause: Issue on our side. Solution: Retry your request after a brief wait and contact us if the issue persists.
NotFoundError	Cause: Requested resource does not exist. Solution: Ensure you are the correct resource identifier.
PermissionDeniedError	Cause: You don't have access to the requested resource. Solution: Ensure you are using the correct API key, organization ID, and resource ID.
RateLimitError	Cause: You have hit your assigned rate limit. Solution: Pace your requests. Read more in our Rate limit guide.
UnprocessableEntityError	Cause: Unable to process the request despite the format being correct. Solution: Please try the request again.

Persistent errors

If an issue persists, contact support via chat and include the model you used, the error message/code, the request data and headers, the timestamp/timezone, and any other relevant details. You can also post in the Community Forum, but do not share sensitive information.

Handling errors

Handle API errors in code and branch on error types where possible. For example:

import openai
from openai import OpenAI

client = OpenAI()

try:
    client.chat.completions.create(model="gpt-4o-mini", prompt="Hi")
except openai.APIError as e:
    print(f"API error: {e}")
except openai.APIConnectionError as e:
    print(f"Connection error: {e}")
except openai.RateLimitError as e:
    print(f"Rate limit: {e}")

Streaming errors

When streaming with SSE, the server can emit an error event.

See The error object for the event schema.