OpenAI API 报错 400、401、403、404、429、500、503 怎么排查：按官方错误码页逐个看原因和解决办法

本文根据 OpenAI 官方《Error codes》和《Rate limits》整理，资料核对于 2026-11-05。配图为本站整理的示意图，不是界面截图。本站（bigolab.com）不是 OpenAI 官方网站。API 是按用量计费的独立服务，与 ChatGPT 订阅分开计算，Key 的获取见 /guides/openai-api-key。

适用于谁

• 调用 OpenAI API 时拿到一个状态码，不知道是代码问题、账号问题还是官方服务问题的开发者；
• 想在程序里把不同错误分开处理的人；
• 想先对号入座，再决定要不要读更长的排查文章的人。

结论先说

1. 先看状态码，再看 error.code。 同样是 429，可能是请求太快，也可能是额度用完、触发了花费上限，处理方法完全不同。
2. 4xx 多半要你自己改：参数、Key、组织、权限、额度。5xx 才是官方一侧的问题。
3. 账单、花费、配额类错误重试没用，官方明确说要先更新额度或上限再发请求。
4. 官方错误码页没有单独写 404。 404 对应的信息只在 Python 库错误类型 NotFoundError 里，本文第四节如实说明。
5. 服务端错误（500、503）：稍等重试，并看官方状态页。

图：本站根据 OpenAI 官方《Error codes》 整理的示意图

一、400：请求本身有问题

官方错误表里 400 有一条：Invalid service_tier argument。原因是你请求的（或自动解析出的）服务层级，该项目不允许使用。官方说明，错误里 error.param 是 service_tier，类型是 invalid_request_error；项目限制针对 default、flex、priority 这几个服务层级，fast 按 priority 计算；就算你没写 service_tier 或写了 auto，只要解析出来的层级不被允许，也会报这个错。解决办法：

• 到项目设置和组织设置里看允许的服务层级，项目不能开启组织已禁用的层级；
• 把 service_tier 设成项目允许的层级；
• 如果你用的是 auto 或没写，就调整项目设置，让解析出的层级被允许。

其他 400 大多对应 Python 库里的 BadRequestError：请求格式不对或缺必需参数。官方的排查步骤是：

• 仔细读错误信息，它会指出哪个参数无效或缺失、期望什么值或格式；
• 对照 API 参考，核对参数名、类型、取值和格式；
• 检查请求数据的编码、格式和大小：UTF-8、JSON，数据太大时压缩；
• 用 Postman 或 curl 单独复现，排除自己代码里的问题。

二、401：认证失败

官方列了四种 401：

1）Invalid Authentication。 凭据无效。可能是用了已撤销的 Key；用了不属于该组织或项目的 Key；Key 没有调用该接口所需的权限。解决：检查请求头里的 Key 和组织是否正确，不确定就重新生成一个并替换。

2）Incorrect API key provided。 Key 不对。可能是有拼写错误或多了空格；用了别的组织或项目的 Key；Key 已被删除或停用；本地缓存了旧的已撤销的 Key。官方建议：清除浏览器缓存和 Cookie 后重试，检查请求头里的 Key，必要时重新生成，并遵循官方的 Key 安全使用最佳实践。Key 怎么申请和保管见 /guides/openai-api-key。

3）You must be a member of an organization to use the API。 你的账号不在任何组织里。可能是离开或被移出了原组织/项目，或组织被删除。解决：向官方申请新组织，或请组织所有者在团队页面邀请你，也可以让项目所有者把你加进项目。

4）IP not authorized。 请求的 IP 与项目或组织配置的 IP 白名单不符。解决：从正确的 IP 发送，或更新 IP 白名单设置。这一条是别人给你的组织设了白名单才会遇到。

三、403：国家、地区不支持

官方表里 403 只有一条：Country, region, or territory not supported，表示你访问 API 的国家、地区不在官方支持范围。官方的解决办法就是看支持国家和地区的页面。本站不提供也不建议任何绕过办法，请以官方 Supported countries 页面为准。

四、404：官方页面里的位置

官方《Error codes》的 API 错误表里没有单独的 404 条目。404 相关的信息只在同页的 Python 库错误类型里：NotFoundError，官方的原因是“请求的资源不存在”，解决办法是确认你使用了正确的资源标识符。

结合官方这句话，本站的排查思路（推断，不是官方逐条说明）是：看看请求路径里和参数里涉及的标识符，例如模型名、文件 ID、响应 ID、批次 ID 有没有写错、是不是已被删除，是不是用了别的项目里的资源。如果是通过 SDK 调用，抛出的是 NotFoundError。

五、429：先看 error.code

429 在官方表里有六条，最重要的是区分 error.code：

图：本站根据 OpenAI 官方《Error codes》 整理的示意图

• credit_balance_exhausted：组织的预付额度用完了。官方的办法是到账单设置里添加额度；
• Rate limit reached for requests：请求太快。放慢节奏，有 Retry-After 就至少等那么久；没有就用带随机抖动的指数退避，并限制重试次数；
• slow_down（类型 rate_limit_error）：请求速度涨得太快，哪怕没超过每分钟请求数和 token 数也会触发。降速后逐步提高；
• organization_spend_limit_exceeded：组织触发了你设置的月度花费上限，调高或取消，否则等到月度上限重置；
• project_spend_limit_exceeded：同理，是项目级的花费上限，其他项目可以继续用；
• organization_usage_limit_exceeded：触发了 OpenAI 分配给组织的月度用量上限，这个与你自己设的花费上限是两回事，可以申请更高的批准用量或联系支持。

官方特别说明：账单相关错误请检查 error.code，因为 error.type 仍可能是 insufficient_quota；重试账单、花费或配额类错误不会恢复访问。

"Rate limit reached for requests" 的常见原因，官方列了：循环或脚本发请求太频繁；和别人共用 Key；免费账号限额低；达到了项目设定的限额。限额按组织算而不是按用户算，团队里别人的用量也会占用。层级与限额见 /guides/openai-api-usage-tiers-rate-limits，具体排查见 /guides/openai-api-429-error。

六、500 和 503：官方一侧

500：服务器处理请求时出错。 官方说原因在它们的服务器。办法：稍等片刻再重试，持续出现就联系官方，并查看官方状态页（status.openai.com）。Python 库对应 InternalServerError，官方的步骤是先等几秒重试，再看状态页有没有进行中的事故或维护。

503：模型暂时过载。 类型 service_unavailable_error，code 是 server_is_overloaded，表示请求的模型暂时没有足够容量处理请求。有 Retry-After 就等那么久再试，没有就拉长重试间隔；持续出现就看状态页。

提醒：Python、TypeScript 等 SDK 里，429 对应 RateLimitError，503 对应 InternalServerError，处理限速和过载时两者都要处理，并检查 error.code。

七、在代码里分开处理

官方的 Node 示例（保存为 .mjs）：

javascript
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("连不上 OpenAI API：", error.message);
  } else if (error instanceof OpenAI.RateLimitError) {
    console.error("请求超过限额：", error.message);
  } else if (error instanceof OpenAI.APIError) {
    console.error("API 返回错误：", error.status, error.message);
  } else {
    throw error;
  }
}

Python 版：

python
import openai
from openai import OpenAI

client = OpenAI()

try:
    response = client.responses.create(model="gpt-6-astra", input="Hello world")
except openai.APIConnectionError as e:
    print("连不上 OpenAI API：", e)
except openai.RateLimitError as e:
    print("请求超过限额：", e)
except openai.APIError as e:
    print("API 返回错误：", e)
else:
    print(response.output_text)

注意 APIError 要放在最后，因为前面两个是它的子类。官方还说明 APIConnectionError 是网络层面的问题，可能是网络设置、代理配置、SSL 证书或防火墙规则；APITimeoutError 是请求耗时太长被服务器断开，等几秒重试。

八、问题一直不好：联系官方时要带什么

官方在 Persistent errors 一节说，持续出错时联系官方支持，并提供：使用的模型；错误信息和 code；发送的请求数据和请求头；请求的时间戳和时区；其他有助于诊断的细节。注意别把 Key 本身发给任何人。

常见问题

Q：同一个请求有时 200 有时 429？

先看是不是 slow_down，或者是批量并发。有关批处理的独立限额，见 /guides/openai-api-batch。

Q：400 说模型不存在？

官方错误码页没有单独写这种情况。按本文第四节的思路核对模型名，并以官方模型页为准。

Q：账单页面看不到额度？

账单和价格见 /guides/openai-api-pricing-billing，价格以官方价格页当天为准。

参考资料

• OpenAI 官方：Error codes — https://developers.openai.com/api/docs/guides/error-codes
• OpenAI 官方：Rate limits — https://developers.openai.com/api/docs/guides/rate-limits