GATE登机口

AI 工具

AI API 报错怎么办?2026 年 401、403、429、5xx 与超时排查表

AI API 报错怎么办?调用 OpenAI、Claude、Gemini 的 API 时,401、403、429、5xx 和超时分别代表什么?本文按状态码逐一说明含义,教你先判断是网络问题还是账号、额度问题,再给出终端代理设置和对应的排查步骤,附三家报错对照表。

发布 · 最后更新 · 登机口编辑

AI API 报错怎么办?先说结论

API 报错先看状态码,再看返回体里的错误类型。粗略分两类:没有收到任何状态码(超时、连接被重置、SSL 握手失败)基本是网络问题,查代理;收到了状态码说明请求已经到达服务器,401 查 Key、403 查地区和权限、429 先区分速率限制还是额度用完、5xx 是服务端问题,等待重试即可。国内开发者最常踩的坑是「浏览器能开官网,代码却超时」,原因是终端不走系统代理,设置环境变量或开 TUN 就能解决。

第一步:判断是网络问题还是账号问题

排查 API 报错最省时间的方法,是先确认请求有没有到达服务器。看下面这张表:

你看到的请求到达服务器了吗问题在哪
超时、连接被拒绝、连接被重置没有网络:代理没生效或节点不通
SSL 或证书相关错误没有完成握手网络:代理配置、中间人或系统时间
401、403、429 等 4xx到了账号、Key、权限、额度或请求内容
500、502、503、529 等 5xx到了服务端或中间网关

只要拿到了 4xx 或 5xx,就说明网络至少是通的,不要再去反复换节点,而是去看控制台和代码。反过来,如果连状态码都没有,改代码、换 Key 都没有用。

调用 API 请遵守各家服务条款和所在地法律法规,使用自己名下的账号和 Key,不要购买或共用来路不明的 Key。

超时与连接错误:终端代理怎么设

国内调用这三家 API,最常见的不是状态码报错,而是请求一直挂着最后超时。几乎都是同一个原因:终端和代码不读系统代理。

方法一:设置环境变量

多数 HTTP 库和 SDK 会读取 HTTPS_PROXY 和 HTTP_PROXY 环境变量。在启动程序的终端里先设置它们,指向本机代理客户端的 HTTP 端口,例如 export HTTPS_PROXY=http://127.0.0.1:端口号(Windows PowerShell 用 $env:HTTPS_PROXY 的写法)。端口号在代理客户端的设置里能看到,Clash 系客户端常见的是混合端口。设置后在同一个终端里运行程序才有效,关掉终端就失效了,需要长期生效可以写进 shell 配置文件。

方法二:开启 TUN 模式

如果程序不读环境变量,或者你在用 IDE、Docker 等不方便逐个设置的环境,可以在代理客户端开启 TUN 模式,让系统所有流量都经过代理。原理和注意事项见 系统代理与 TUN 模式。

验证代理是否生效

在同一个终端里用 curl -I 请求一下对应 API 的域名,能在几秒内返回状态码(哪怕是 401 或 404)就说明网络通了。如果仍然超时,检查代理客户端是否在运行、端口是否正确、节点本身能不能用,节点问题可以看 节点超时。编程工具的代理设置在 AI 编程工具网络设置 里有更完整的说明。

SSL 错误

出现证书校验失败、握手失败时,先检查系统时间是否准确,再确认代理地址写的是 http:// 而不是 https://(大多数本地代理端口是 HTTP 代理),最后看是不是公司网络或安全软件在做 HTTPS 拦截。

401:认证失败

401 的意思是服务器不认你的身份,和网络无关。常见原因:

  • Key 复制不完整,开头或结尾多了空格、换行。
  • Key 已被删除或吊销,或者用的是别的项目、别的组织的 Key。
  • 请求头写错。OpenAI 用 Authorization: Bearer 加 Key;Claude 用 x-api-key 请求头,并且需要带 anthropic-version;Gemini 用 x-goog-api-key 请求头或 URL 参数传 Key。三家写法不同,混用就会 401 或 400。
  • 环境变量里有一个旧 Key,覆盖了你在代码里写的新 Key。

排查方法:在控制台重新生成一个 Key,用最简单的 curl 请求测试。curl 能通而代码不通,问题就在代码读取 Key 的方式上。

403:权限或地区被拒绝

403 说明服务器认出了你,但不允许这次请求。对国内开发者来说,分两种情况:

地区不支持

OpenAI 和 Claude 的 API 都有支持地区名单,来自不支持地区的请求会被拒绝,错误信息里通常会提到国家、地区或领土不受支持。这时候需要确认你的出口 IP 在支持地区,比如美国、日本、新加坡,具体名单以官方说明为准。注意香港通常不在 OpenAI 和 Claude 的支持范围内,用香港节点调用很容易遇到这个错误。原理可以看 为什么 AI 服务在意 IP。Gemini API 遇到地区限制时,返回的可能是 400 并提示用户所在位置不受支持,而不是 403,排查思路相同。

权限不足

Key 没有访问某个模型或功能的权限、项目被限制、组织设置了访问策略,都会返回 403。这种情况换节点没有用,去控制台检查项目权限和模型可用性。

429:速率限制还是额度用完

429 是国内开发者最容易误判的状态码,因为它包含两种性质完全不同的情况:

类型怎么识别怎么处理
速率限制错误信息提到 rate limit、每分钟请求数或 token 数降低并发、加退避重试,等待几秒到一分钟
额度不足错误信息提到 quota、余额、账单去控制台检查余额、支付方式和用量上限

OpenAI 在额度用完时也返回 429,错误类型会标明是额度不足,这种情况等多久都不会恢复。Gemini 的 429 通常带资源耗尽的状态,免费层的每分钟、每天限额都比付费层低很多。Claude 的 429 是速率限制,响应头里会给出建议的重试等待时间。

处理速率限制的标准做法是指数退避重试:第一次失败等 1 秒,第二次等 2 秒,第三次等 4 秒,以此类推,并设一个最大重试次数。官方 SDK 大多内置了这个逻辑,只需要调大重试次数即可。网页端 ChatGPT 的「请求过多」是另一回事,见 ChatGPT 请求过多。

5xx:服务端错误

5xx 表示请求到了服务器,但服务器自己出了问题:

  • 500:服务器内部错误,偶发的话直接重试。
  • 502 / 504:网关错误或网关超时,可能是服务端负载高,也可能是你和服务器之间的代理链路不稳定。长回复的请求更容易遇到 504,可以改用流式输出。
  • 503:服务暂时不可用,常见于高峰期或维护期间。
  • 529:Claude API 特有,表示服务过载,等待后重试即可。

长回复还有一个容易被忽略的点:官方 SDK 和很多 HTTP 库都有默认的读取超时,模型生成一段很长的回答可能超过这个时间,客户端就会自己断开并报超时,看起来像网络问题,其实服务器还在正常工作。解决办法是把客户端的超时时间调大,或者改用流式输出,让数据边生成边返回。如果中间经过了自建反向代理或网关,也要同步调大它们的超时设置,否则依然会在网关那一层被切断,返回 504。

遇到 5xx,先去对应服务的官方状态页看看是不是大面积故障。如果状态页一切正常、只有你持续出错,再检查请求体是否过大、模型名是否写错,以及代理节点在长连接下是否稳定。频繁断线的节点可以看 频繁断线排查。

三家常见报错对照表

状态码OpenAIClaudeGemini先查什么
400参数错误请求格式错误参数错误,或所在地区不支持请求体、模型名、出口地区
401Key 无效认证失败多以 400 或 403 提示 Key 无效Key 和请求头
403地区不支持或无权限权限不足或地区限制权限被拒绝出口地区、项目权限
404模型或路径不存在资源不存在模型或路径不存在模型名拼写、接口路径
429速率限制或额度不足速率限制资源耗尽错误类型、账单与限额
5xx500、503 常见500,过载时 529500、503 常见官方状态页,重试
无状态码超时或连接重置超时或连接重置超时或 SSL 错误终端代理、节点

具体错误类型的英文写法以各家官方文档为准,上表只列出含义。

节点和机场怎么选

API 调用对节点的要求比网页使用更明确:出口在支持地区、IP 固定、长连接稳定。建议在代理客户端里给 API 域名单独设一个策略组,手动指定美国或日本节点,不要用自动测速。批量调用的程序如果中途换出口,可能导致部分请求失败。三家服务各自的地区和网络细节,可以分别看 ChatGPT、Claude、Gemini 和 Google AI Studio 几篇。

根据公开资料,二猫云 标注支持 ChatGPT、Claude、Gemini 等,光速云 标注支持 ChatGPT、Claude、Gemini 并宣称提供原生 IP,这些都是官方说法,本站没有做过实测。更多候选在 机场推荐清单 和 AI 场景机场 里,选之前建议先月付,用自己的程序跑一段时间确认稳定性。

常见问题

AI API 报错怎么办?

API 报错先看状态码,再看返回体里的错误类型。粗略分两类:没有收到任何状态码(超时、连接被重置、SSL 握手失败)基本是网络问题,查代理;收到了状态码说明请求已经到达服务器,401 查 Key、403 查地区和权限、429 先区分速率限制还是额度用完、5xx 是服务端问题,等待重试即可。

API 返回 429 一定是请求太快吗?

不一定。429 有两种常见情况:一种是单位时间内请求或 token 数超过了速率限制,等一会儿或降低并发就好;另一种是账户额度用完或没有可用余额,等多久都不会恢复,需要去控制台检查账单和额度。看返回体里的错误类型就能区分。

403 和地区有什么关系?

OpenAI 和 Claude 的 API 会根据请求来源判断地区,来自不支持地区的请求可能直接返回 403,并在错误信息里提到地区或国家不受支持。这时换到支持地区的出口通常就能恢复,具体支持名单以官方说明为准。

为什么浏览器能打开官网,代码调用 API 却超时?

浏览器走的是系统代理,而终端和大多数编程语言的 HTTP 库默认不读系统代理设置,请求实际上是直连出去的,自然会超时。设置 HTTPS_PROXY 环境变量或者开启 TUN 模式即可。

5xx 错误需要我做什么吗?

5xx 是服务端出错,大多数情况你什么都不用改,等一会儿重试即可。建议在代码里加上带退避的自动重试,并关注官方状态页。如果长时间只有你一个人遇到,再检查是不是请求体过大或者模型名写错。

API Key 能不能放在前端代码里?

不能。前端代码任何人都能看到,Key 泄露后别人可以用你的额度调用,产生费用。Key 应该只放在服务端或本地环境变量里,发现泄露要立即在控制台吊销并重新生成。

本站主推:星岛梦 2020 年开业的老牌机场,12 个地区、套餐形式多。主打「超量 150G」¥25/月 / 150GB,年付小包 ¥96(折合 ¥8/月),资料分 9.5(第 1),优惠码 nmw888(新人注册 9 折)。

去星岛梦官网星岛梦完整评测