Repository Public
1# Error codes23> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.45This guide includes an overview on error codes you might see from both the [API](https://developers.openai.com/api/docs/concepts) and our [official Python library](https://developers.openai.com/api/docs/libraries#install-an-official-sdk). Each error code mentioned in the overview has a dedicated section with further guidance.67## API errors89| Code | Overview |10| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |11| 400 - Invalid `service_tier` argument | **Cause:** The requested or resolved service tier is not allowed for the project. <br /> **Solution:** Set `service_tier` to a tier allowed for the project, or update the allowed service tiers in [project settings](https://platform.openai.com/settings/). |12| 401 - Invalid Authentication | **Cause:** Invalid Authentication <br /> **Solution:** Ensure the correct [API key](https://platform.openai.com/settings/organization/api-keys) and requesting organization are being used. |13| 401 - Incorrect API key provided | **Cause:** The requesting API key is not correct. <br /> **Solution:** Ensure the API key used is correct, clear your browser cache, or [generate a new one](https://platform.openai.com/settings/organization/api-keys). |14| 401 - You must be a member of an organization to use the API | **Cause:** Your account is not part of an organization. <br /> **Solution:** Contact us to get added to a new organization or ask your organization manager to [invite you to an organization](https://platform.openai.com/settings/organization/people). |15| 401 - IP not authorized | **Cause:** Your request IP does not match the configured IP allowlist for your project or organization. <br /> **Solution:** Send the request from the correct IP, or update your [IP allowlist settings](https://platform.openai.com/settings/organization/security/ip-allowlist). |16| 403 - Country, region, or territory not supported | **Cause:** You are accessing the API from an unsupported country, region, or territory. <br /> **Solution:** Please see [this page](https://developers.openai.com/api/docs/supported-countries) for more information. |17| 429 - Credit balance exhausted | **Code:** `credit_balance_exhausted` <br /> **Cause:** Your organization has no prepaid credits remaining. <br /> **Solution:** [Add credits](https://platform.openai.com/settings/organization/billing) to continue using the API. |18| 429 - Rate limit reached for requests | **Cause:** You are sending requests too quickly. <br /> **Solution:** Pace your requests and follow the `Retry-After` header when it's present. Read the [Rate limit guide](https://developers.openai.com/api/docs/guides/rate-limits). |19| 429 - Slow down | **Type:** `rate_limit_error` <br /> **Code:** `slow_down` <br /> **Cause:** Your request rate increased too quickly. <br /> **Solution:** Follow the `Retry-After` header when it's present, reduce your request rate, and increase it gradually. |20| 429 - Organization spend limit reached | **Code:** `organization_spend_limit_exceeded` <br /> **Cause:** Your organization reached its enforced spend limit. <br /> **Solution:** Increase or remove your [organization spend limit](https://platform.openai.com/settings/organization/limits). |21| 429 - Project spend limit reached | **Code:** `project_spend_limit_exceeded` <br /> **Cause:** Your project reached its enforced spend limit. <br /> **Solution:** Increase or remove the spend limit in your [project settings](https://platform.openai.com/settings/). |22| 429 - Organization usage limit reached | **Code:** `organization_usage_limit_exceeded` <br /> **Cause:** Your organization reached its OpenAI-assigned usage limit. <br /> **Solution:** Request a higher [approved usage limit](https://platform.openai.com/settings/organization/limits) or [contact support](https://help.openai.com/). |23| 500 - The server had an error while processing your request | **Cause:** Issue on our servers. <br /> **Solution:** Retry your request after a brief wait and contact us if the issue persists. Check the [status page](https://status.openai.com/). |24| 503 - Model temporarily overloaded | **Type:** `service_unavailable_error` <br /> **Code:** `server_is_overloaded` <br /> **Cause:** The requested model is temporarily overloaded. <br /> **Solution:** Follow the `Retry-After` header when it's present, then retry your request. |2526For billing-related errors, inspect `error.code` to identify the specific cause. The broader `error.type` can still be `insufficient_quota`.2728Retrying billing, spend, or quota errors won't restore API access. Update the relevant credits or limits before sending another request.2930## WebSocket mode errors3132If you are using [the Responses API WebSocket mode](https://developers.openai.com/api/docs/guides/websocket-mode), you may see these additional errors:3334- `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`.35- `websocket_connection_limit_reached`: The connection hit the 60-minute limit. Open a new WebSocket connection and continue.36373839### 400 - Invalid service_tier argument404142The API returns the message "Invalid service_tier argument: The requested service tier is not allowed for this project." as an `invalid_request_error` with `error.param` set to `service_tier` when a request selects or resolves to a service tier that is not allowed for the project.4344Project restrictions apply to the `default`, `flex`, and `priority` service tiers. The `fast` service tier is evaluated as `priority`. Requests that omit `service_tier` or set it to `auto` can also return this error if they resolve to a disallowed tier. Scale Tier remains outside this project policy.4546To resolve this error:4748- Check the allowed service tiers in [project settings](https://platform.openai.com/settings/).49- Set `service_tier` to a tier allowed for the project.50- If the request uses `auto` or omits `service_tier`, update the project settings so the resolved tier is allowed.5152535455565758### 401 - Invalid Authentication596061This error message indicates that your authentication credentials are invalid. This could happen for several reasons, such as:6263- You are using a revoked API key.64- You are using a different API key than the one assigned to the requesting organization or project.65- You are using an API key that does not have the required permissions for the endpoint you are calling.6667To resolve this error, please follow these steps:6869- Check that you are using the correct API key and organization ID in your request header. You can find your API key and organization ID in [your account settings](https://platform.openai.com/settings/organization/api-keys) or your can find specific project related keys under [General settings](https://platform.openai.com/settings/organization/general) by selecting the desired project.70- If you are unsure whether your API key is valid, you can [generate a new one](https://platform.openai.com/settings/organization/api-keys). Make sure to replace your old API key with the new one in your requests and follow our [best practices guide](https://help.openai.com/en/articles/5112595-best-practices-for-api-key-safety).7172737475767778### 401 - Incorrect API key provided798081This error message indicates that the API key you are using in your request is not correct. This could happen for several reasons, such as:8283- There is a typo or an extra space in your API key.84- You are using an API key that belongs to a different organization or project.85- You are using an API key that has been deleted or deactivated.86- An old, revoked API key might be cached locally.8788To resolve this error, please follow these steps:8990- Try clearing your browser's cache and cookies, then try again.91- Check that you are using the correct API key in your request header.92- If you are unsure whether your API key is correct, you can [generate a new one](https://platform.openai.com/settings/organization/api-keys). Make sure to replace your old API key in your codebase and follow our [best practices guide](https://help.openai.com/en/articles/5112595-best-practices-for-api-key-safety).93949596979899100### 401 - You must be a member of an organization to use the API101102103This error message indicates that your account is not part of an organization. This could happen for several reasons, such as:104105- You have left or been removed from your previous organization.106- You have left or been removed from your previous project.107- Your organization has been deleted.108109To resolve this error, please follow these steps:110111- If you have left or been removed from your previous organization, you can either request a new organization or get invited to an existing one.112- To request a new organization, reach out to us via help.openai.com113- Existing organization owners can invite you to join their organization via the [Team page](https://platform.openai.com/settings/organization/people) or can create a new project from the [Settings page](https://platform.openai.com/settings/organization/general).114- If you have left or been removed from a previous project, you can ask your organization or project owner to add you to it, or create a new one.115116117118119120121122### 429 - Credit balance exhausted123124125The `credit_balance_exhausted` error indicates that your organization's prepaid credit balance is depleted.126127To restore API access, [add credits in your billing settings](https://platform.openai.com/settings/organization/billing).128129130131132133134135### 429 - Rate limit reached for requests136137138This error message indicates that you have hit your assigned rate limit for the API. This means that you have submitted too many tokens or requests in a short period of time and have exceeded the number of requests allowed. This could happen for several reasons, such as:139140- You are using a loop or a script that makes frequent or concurrent requests.141- You are sharing your API key with other users or applications.142- You are using a free plan that has a low rate limit.143- You have reached the defined limit on your project144145To resolve this error, please follow these steps:146147- Pace your requests and avoid making unnecessary or redundant calls.148- If a `Retry-After` header is present, wait at least as long as it specifies before trying again. If it's missing, use exponential backoff with jitter and limit the number of retries. SDK support for long server delays varies by version and configuration. Read more in our [rate limit guide](https://developers.openai.com/api/docs/guides/rate-limits#retrying-with-exponential-backoff).149- If you are sharing your organization with other users, note that limits are applied per organization and not per user. It is worth checking on the usage of the rest of your team as this will contribute to the limit.150- If you are using a free or low-tier plan, consider upgrading to a pay-as-you-go plan that offers a higher rate limit. You can compare the restrictions of each plan in our [rate limit guide](https://developers.openai.com/api/docs/guides/rate-limits).151- Reach out to your organization owner to increase the rate limits on your project152153154155156157158159### 429 - Slow down160161162A `429` response with the `rate_limit_error` type and `slow_down` code indicates that your request rate increased faster than the service can safely handle. It can occur even when your traffic is within its requests-per-minute and tokens-per-minute limits.163164As a rule of thumb, once your traffic reaches 1 million input tokens per minute (TPM), increase it by no more than 50% every 15 minutes. The exact point at which the ramp-rate limit applies can vary by model and traffic conditions.165166To resolve this error:167168- If a `Retry-After` header is present, wait at least as long as it specifies before retrying. If it's missing, increase the delay between retries and add a small random delay.169- Reduce your request rate, then increase it gradually.170- Keep your traffic pattern steady to reduce the chance of another `slow_down` error.171172Enterprise customers whose pay-as-you-go traffic routinely hits ramp-rate limits can consider [Scale Tier](https://openai.com/api-scale-tier/) for more predictable capacity on eligible models. For GPT-5.6 and later models, see [Reserved Tier](https://openai.com/api-reserved-tier/). These capacity options don't replace the recovery steps above: continue to follow `Retry-After` when it's present and ramp traffic gradually.173174175176177178179180### 429 - Organization spend limit reached181182183The `organization_spend_limit_exceeded` error indicates that your organization reached its enforced monthly [spend limit](https://developers.openai.com/api/docs/guides/spend-limits). The limit applies to API traffic across all projects in the organization.184185To restore API access, increase or remove the limit in your [organization limit settings](https://platform.openai.com/settings/organization/limits). Otherwise, access resumes after the monthly limit resets.186187188189190191192193### 429 - Project spend limit reached194195196The `project_spend_limit_exceeded` error indicates that your project reached its enforced monthly [spend limit](https://developers.openai.com/api/docs/guides/spend-limits). Other projects can continue unless their own limit or the organization limit is also reached.197198To restore API access, increase or remove the limit in your [project settings](https://platform.openai.com/settings/). Otherwise, access resumes after the monthly limit resets.199200201202203204205206### 429 - Organization usage limit reached207208209The `organization_usage_limit_exceeded` error indicates that your organization reached its OpenAI-assigned monthly [usage limit](https://developers.openai.com/api/docs/guides/rate-limits#usage-tiers). This limit is separate from organization and project spend limits that you configure.210211To restore API access, request a higher [approved usage limit](https://platform.openai.com/settings/organization/limits) or [contact support](https://help.openai.com/).212213214215216217218219### 503 - Model temporarily overloaded220221222A `503` response with the `service_unavailable_error` type and `server_is_overloaded` code indicates that the requested model does not have enough capacity to process your request at the moment.223224If a `Retry-After` header is present, wait at least as long as it specifies before retrying. If it's missing, increase the delay between retries. If the error continues, check the [status page](https://status.openai.com/) for an active incident.225226227228229230## Python library error types231232Python 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](https://developers.openai.com/api/docs/guides/rate-limits#update-existing-error-handlers) for the endpoint-specific changes.233234| Type | Overview |235| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |236| APIConnectionError | **Cause:** Issue connecting to our services. <br /> **Solution:** Check your network settings, proxy configuration, SSL certificates, or firewall rules. |237| APITimeoutError | **Cause:** Request timed out. <br /> **Solution:** Retry your request after a brief wait and contact us if the issue persists. |238| AuthenticationError | **Cause:** Your API key or token was invalid, expired, or revoked. <br /> **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. |239| BadRequestError | **Cause:** Your request was malformed or missing some required parameters, such as a token or an input. <br /> **Solution:** The error message should advise you on the specific error made. Check the [documentation](https://developers.openai.com/api/reference/overview) 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. |240| ConflictError | **Cause:** The resource was updated by another request. <br /> **Solution:** Try to update the resource again and ensure no other requests are trying to update it. |241| InternalServerError | **Cause:** Issue on our side. <br /> **Solution:** Retry your request after a brief wait and contact us if the issue persists. |242| NotFoundError | **Cause:** Requested resource does not exist. <br /> **Solution:** Ensure you are the correct resource identifier. |243| PermissionDeniedError | **Cause:** You don't have access to the requested resource. <br /> **Solution:** Ensure you are using the correct API key, organization ID, and resource ID. |244| RateLimitError | **Cause:** You have hit your assigned rate limit or increased traffic too quickly. <br /> **Solution:** Pace your requests and follow `Retry-After` when it's present, subject to your retry limits. Read more in our [Rate limit guide](https://developers.openai.com/api/docs/guides/rate-limits#retrying-with-exponential-backoff). |245| UnprocessableEntityError | **Cause:** Unable to process the request despite the format being correct. <br /> **Solution:** Please try the request again. |246247248249### APIConnectionError250251252An `APIConnectionError` indicates that your request could not reach our servers or establish a secure connection. This could be due to a network issue, a proxy configuration, an SSL certificate, or a firewall rule.253254If you encounter an `APIConnectionError`, please try the following steps:255256- Check your network settings and make sure you have a stable and fast internet connection. You may need to switch to a different network, use a wired connection, or reduce the number of devices or applications using your bandwidth.257- Check your proxy configuration and make sure it is compatible with our services. You may need to update your proxy settings, use a different proxy, or bypass the proxy altogether.258- Check your SSL certificates and make sure they are valid and up-to-date. You may need to install or renew your certificates, use a different certificate authority, or disable SSL verification.259- Check your firewall rules and make sure they are not blocking or filtering our services. You may need to modify your firewall settings.260- If appropriate, check that your container has the correct permissions to send and receive traffic.261- If the issue persists, check out our persistent errors next steps section.262263264265266267268269### APITimeoutError270271272A `APITimeoutError` error indicates that your request took too long to complete and our server closed the connection. This could be due to a network issue, a heavy load on our services, or a complex request that requires more processing time.273274If you encounter a `APITimeoutError` error, please try the following steps:275276- Wait a few seconds and retry your request. Sometimes, the network congestion or the load on our services may be reduced and your request may succeed on the second attempt.277- Check your network settings and make sure you have a stable and fast internet connection. You may need to switch to a different network, use a wired connection, or reduce the number of devices or applications using your bandwidth.278- If the issue persists, check out our persistent errors next steps section.279280281282283284285286### AuthenticationError287288289An `AuthenticationError` indicates that your API key or token was invalid, expired, or revoked. This could be due to a typo, a formatting error, or a security breach.290291If you encounter an `AuthenticationError`, please try the following steps:292293- Check your API key or token and make sure it is correct and active. You may need to generate a new key from the API Key dashboard, ensure there are no extra spaces or characters, or use a different key or token if you have multiple ones.294- Ensure that you have followed the correct formatting.295296297298299300301302### BadRequestError303304305306An `BadRequestError` (formerly `InvalidRequestError`) indicates that your request was malformed or missing some required parameters, such as a token or an input. This could be due to a typo, a formatting error, or a logic error in your code.307308If you encounter an `BadRequestError`, please try the following steps:309310- Read the error message carefully and identify the specific error made. The error message should advise you on what parameter was invalid or missing, and what value or format was expected.311- Check the [API Reference](https://developers.openai.com/api/reference/overview) for the specific API method you were calling and make sure you are sending valid and complete parameters. You may need to review the parameter names, types, values, and formats, and ensure they match the documentation.312- Check the encoding, format, or size of your request data and make sure they are compatible with our services. You may need to encode your data in UTF-8, format your data in JSON, or compress your data if it is too large.313- Test your request using a tool like Postman or curl and make sure it works as expected. You may need to debug your code and fix any errors or inconsistencies in your request logic.314- If the issue persists, check out our persistent errors next steps section.315316317318319320321322### InternalServerError323324325An `InternalServerError` indicates that something went wrong on our side when processing your request. This could be due to a temporary error, a bug, or a system outage.326327We apologize for any inconvenience and we are working hard to resolve any issues as soon as possible. You can [check our system status page](https://status.openai.com/) for more information.328329If you encounter an `InternalServerError`, please try the following steps:330331- Wait a few seconds and retry your request. Sometimes, the issue may be resolved quickly and your request may succeed on the second attempt.332- Check our status page for any ongoing incidents or maintenance that may affect our services. If there is an active incident, please follow the updates and wait until it is resolved before retrying your request.333- If the issue persists, check out our Persistent errors next steps section.334335Our 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](https://community.openai.com) but be sure to omit any sensitive information.336337338339340341342343### RateLimitError344345346A `RateLimitError` indicates that you have hit your assigned rate limit. This means that you have sent too many tokens or requests in a given period of time, and our services have temporarily blocked you from sending more.347348We impose rate limits to ensure fair and efficient use of our resources and to prevent abuse or overload of our services.349350If you encounter a `RateLimitError`, please try the following steps:351352- Send fewer tokens or requests or slow down. You may need to reduce the frequency or volume of your requests, batch your tokens, or use exponential backoff when `Retry-After` isn't present. You can read our [Rate limit guide](https://developers.openai.com/api/docs/guides/rate-limits) for more details.353- When `Retry-After` is present, wait at least as long as it specifies before retrying. The Python library can stop automatic retries when a server delay exceeds its supported limit. If you retry at the application level, respect the original delay and account for SDK retries.354- You can also check your API usage statistics from your account dashboard.355356357358359360### Persistent errors361362If the issue persists, [contact our support team via chat](https://help.openai.com/en/) and provide them with the following information:363364- The model you were using365- The error message and code you received366- The request data and headers you sent367- The timestamp and timezone of your request368- Any other relevant details that may help us diagnose the issue369370Our 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](https://community.openai.com) but be sure to omit any sensitive information.371372### Handling errors373374We advise you to programmatically handle errors returned by the API. To do so, you may want to use a code snippet like below:375376```javascript377import OpenAI from "openai";378379const client = new OpenAI();380381try {382 const response = await client.responses.create({383 model: "gpt-6-astra",384 input: "Hello world",385 });386 console.log(response.output_text);387} catch (error) {388 if (error instanceof OpenAI.APIConnectionError) {389 console.error("Failed to connect to the OpenAI API:", error.message);390 } else if (error instanceof OpenAI.RateLimitError) {391 console.error("OpenAI API request exceeded its rate limit:", error.message);392 } else if (error instanceof OpenAI.APIError) {393 console.error("OpenAI API returned an error:", error.status, error.message);394 } else {395 throw error;396 }397}398```399400```python401import openai402from openai import OpenAI403404client = OpenAI()405406try:407 response = client.responses.create(model="gpt-6-astra", input="Hello world")408except openai.APIConnectionError as e:409 print(f"Failed to connect to OpenAI API: {e}")410except openai.RateLimitError as e:411 print(f"OpenAI API request exceeded rate limit: {e}")412except openai.APIError as e:413 print(f"OpenAI API returned an API Error: {e}")414else:415 print(response.output_text)416```417418```go419package main420421import (422 "context"423 "errors"424 "fmt"425426 "github.com/openai/openai-go/v3"427 "github.com/openai/openai-go/v3/responses"428)429430func main() {431 client := openai.NewClient()432 response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{433 Model: "gpt-6-astra",434 Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("Hello world")},435 })436 if err != nil {437 var apiError *openai.Error438 if errors.As(err, &apiError) {439 fmt.Println("OpenAI API returned an API error:", apiError)440 return441 }442 fmt.Println("Failed to connect to OpenAI API:", err)443 return444 }445 fmt.Println(response.OutputText())446}447```448449```java450import com.openai.client.OpenAIClient;451import com.openai.client.okhttp.OpenAIOkHttpClient;452import com.openai.errors.OpenAIServiceException;453import com.openai.models.responses.ResponseCreateParams;454455try {456 var response =457 client458 .responses()459 .create(460 ResponseCreateParams.builder().model("gpt-6-astra").input("Say hello.").build());461462 response.output().stream()463 .flatMap(item -> item.message().stream())464 .flatMap(message -> message.content().stream())465 .flatMap(content -> content.outputText().stream())466 .forEach(text -> System.out.println(text.text()));467} catch (OpenAIServiceException error) {468 System.err.println(error.getMessage());469}470```471472```ruby473require "openai"474475client = OpenAI::Client.new476begin477 response = client.responses.create(model: "gpt-6-astra", input: "Say hello.")478 puts(response.output_text)479rescue OpenAI::Errors::APIError => error480 warn(error.message)481end482```