Documentation 2026-07-28 23:01 UTC to 2026-07-29 22:58 UTC

7## API errors7## API errors

8 8 

9| Code | Overview |9| Code | Overview |

10| --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |10| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

11| 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. |11| 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. |

12| 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). |12| 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). |

13| 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). |13| 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). |

14| 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). |14| 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). |

15| 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. |15| 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. |

16| 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. |

16| 429 - Rate limit reached for requests | **Cause:** You are sending requests too quickly. <br /> **Solution:** Pace your requests. Read the [Rate limit guide](https://developers.openai.com/api/docs/guides/rate-limits). |17| 429 - Rate limit reached for requests | **Cause:** You are sending requests too quickly. <br /> **Solution:** Pace your requests. Read the [Rate limit guide](https://developers.openai.com/api/docs/guides/rate-limits). |

17| 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. <br /> **Solution:** [Buy more credits](https://platform.openai.com/settings/organization/billing) or learn how to [increase your limits](https://platform.openai.com/settings/organization/limits). |18| 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). |

19| 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/). |

20| 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/). |

18| 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/). |21| 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/). |

19| 503 - The engine is currently overloaded, please try again later | **Cause:** Our servers are experiencing high traffic. <br /> **Solution:** Please retry your requests after a brief wait. |22| 503 - The engine is currently overloaded, please try again later | **Cause:** Our servers are experiencing high traffic. <br /> **Solution:** Please retry your requests after a brief wait. |

20| 503 - Slow Down | **Cause:** A sudden increase in your request rate is impacting service reliability. <br /> **Solution:** Please reduce your request rate to its original level, maintain a consistent rate for at least 15 minutes, and then gradually increase it. |23| 503 - Slow Down | **Cause:** A sudden increase in your request rate is impacting service reliability. <br /> **Solution:** Please reduce your request rate to its original level, maintain a consistent rate for at least 15 minutes, and then gradually increase it. |

21 24 

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

26 

22## WebSocket mode errors27## WebSocket mode errors

23 28 

24If you are using [the Responses API WebSocket mode](https://developers.openai.com/api/docs/guides/websocket-mode), you may see these additional errors:29If you are using [the Responses API WebSocket mode](https://developers.openai.com/api/docs/guides/websocket-mode), you may see these additional errors:

69- 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).74- 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).

70- 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.75- 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.

71 76 

77429 - Credit balance exhausted

78 

79The `credit_balance_exhausted` error indicates that your organization's prepaid credit balance is depleted.

80 

81To restore API access, [add credits in your billing settings](https://platform.openai.com/settings/organization/billing).

82 

72429 - Rate limit reached for requests83429 - Rate limit reached for requests

73 84 

74This 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:85This 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:

86- 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).97- 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).

87- Reach out to your organization owner to increase the rate limits on your project98- Reach out to your organization owner to increase the rate limits on your project

88 99 

89429 - You exceeded your current quota, please check your plan and billing details100429 - Organization spend limit reached

101 

102The `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.

103 

104To 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.

105 

106429 - Project spend limit reached

107 

108The `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.

109 

110To 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.

90 111 

91This error message indicates that the organization exhausted its prepaid credits, reached its OpenAI-approved monthly [usage limit](https://platform.openai.com/settings/organization/limits), or reached an enforced organization or project [spend limit](https://developers.openai.com/api/docs/guides/spend-limits).112429 - Organization usage limit reached

92 113 

93To resolve this error:114The `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.

94 115 

95- Compare [current usage](https://platform.openai.com/settings/organization/usage) with the organization's approved usage limit and applicable organization or project spend limits.116To restore API access, request a higher [approved usage limit](https://platform.openai.com/settings/organization/limits) or [contact support](https://help.openai.com/).

96- [Buy more credits](https://platform.openai.com/settings/organization/billing) or request a higher approved usage limit when needed.

97- Raise or remove the applicable hard spend limit if API traffic should resume before the monthly reset.

98 117 

99503 - The engine is currently overloaded, please try again later118503 - The engine is currently overloaded, please try again later

100 119 

4 4 

5Secure MCP Tunnel lets you connect private MCP servers to supported OpenAI products without opening inbound firewall ports or exposing those servers to the public internet. Run `tunnel-client` inside the network that can already reach your MCP server; it opens an outbound HTTPS path to OpenAI, pulls queued MCP work, forwards requests locally, and returns responses through the same tunnel.5Secure MCP Tunnel lets you connect private MCP servers to supported OpenAI products without opening inbound firewall ports or exposing those servers to the public internet. Run `tunnel-client` inside the network that can already reach your MCP server; it opens an outbound HTTPS path to OpenAI, pulls queued MCP work, forwards requests locally, and returns responses through the same tunnel.

6 6 

7Secure MCP Tunnel supports private MCP connections, including developer-mode

8 testing. It does not support public plugin submission or distribution. Public

9 plugins require a stable, publicly reachable HTTPS MCP endpoint. If the MCP

10 server must stay private, expose a public HTTPS proxy that forwards requests

11 to it. See [public plugin submission](https://developers.openai.com/plugins/deploy/submission) for endpoint

12 and authentication requirements.

13 

7## What is an MCP tunnel?14## What is an MCP tunnel?

8 15 

9An MCP tunnel is an outbound-only connection from a host inside your network to an OpenAI-hosted MCP endpoint. Use it when your MCP server is private, on-premises, or behind a firewall, but ChatGPT, Codex, the Responses API, or another supported OpenAI surface still needs to call it.16An MCP tunnel is an outbound-only connection from a host inside your network to an OpenAI-hosted MCP endpoint. Use it when your MCP server is private, on-premises, or behind a firewall, but ChatGPT, Codex, the Responses API, or another supported OpenAI surface still needs to call it.

6 6 

7Hard spend limits can interrupt production traffic. When tracked spend reaches7Hard spend limits can interrupt production traffic. When tracked spend reaches

8 an applicable hard limit, affected API requests return a `429` error with the8 an applicable hard limit, affected API requests return a `429` error with the

9 `insufficient_quota` code. Enforcement is not instantaneous, so recorded spend9 `organization_spend_limit_exceeded` or `project_spend_limit_exceeded` code.

10 can slightly exceed the configured amount.10 Enforcement is not instantaneous, so recorded spend can slightly exceed the

11 configured amount.

11 12 

12## Choose a spend control13## Choose a spend control

13 14 

60 61 

61- An organization hard limit applies to API traffic across all projects in the organization.62- An organization hard limit applies to API traffic across all projects in the organization.

62- A project hard limit applies only to API traffic billed to that project.63- A project hard limit applies only to API traffic billed to that project.

63- Reaching either applicable hard limit causes affected requests to return `429` errors with the `insufficient_quota` code.64- Reaching an organization hard limit returns a `429` error with the `organization_spend_limit_exceeded` code.

65- Reaching a project hard limit returns a `429` error with the `project_spend_limit_exceeded` code.

64- Raising or removing the reached limit allows traffic to resume after the update propagates. Otherwise, the limit resets with the next monthly cycle.66- Raising or removing the reached limit allows traffic to resume after the update propagates. Otherwise, the limit resets with the next monthly cycle.

65 67 

66Enforcement is not instantaneous. The API Platform can process a small amount of extra usage while the limit state propagates, so recorded spend can slightly exceed the configured amount.68Enforcement is not instantaneous. The API Platform can process a small amount of extra usage while the limit state propagates, so recorded spend can slightly exceed the configured amount.

71 73 

72## Restore API traffic74## Restore API traffic

73 75 

74If requests return quota-related `429` errors:76If requests fail because of a billing-related limit or credit balance:

75 77 

761. Compare [current usage](https://platform.openai.com/settings/organization/usage) with the organization and project spend limits that apply to the request.781. Check `error.code` to identify whether the request reached an organization spend limit, project spend limit, or OpenAI-assigned usage limit, or whether the organization exhausted its prepaid credits.

772. Raise or remove the reached hard limit if traffic should resume before the monthly reset.792. For `organization_spend_limit_exceeded` or `project_spend_limit_exceeded`, compare [current usage](https://platform.openai.com/settings/organization/usage) with your spend limits. Raise or remove the reached limit if traffic should resume before the monthly reset.

783. If tracked spend is below every applicable hard limit, check whether the organization exhausted prepaid credits or reached its OpenAI-approved usage limit.803. For `organization_usage_limit_exceeded`, request a higher [approved usage limit](https://platform.openai.com/settings/organization/limits).

794. If the error reports a request or token rate limit instead of `insufficient_quota`, follow the [rate limit guide](https://developers.openai.com/api/docs/guides/rate-limits).814. For `credit_balance_exhausted`, [add credits](https://platform.openai.com/settings/organization/billing).

825. If the error reports a request or token rate limit, follow the [rate limit guide](https://developers.openai.com/api/docs/guides/rate-limits).