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,先去对应服务的官方状态页看看是不是大面积故障。如果状态页一切正常、只有你持续出错,再检查请求体是否过大、模型名是否写错,以及代理节点在长连接下是否稳定。频繁断线的节点可以看 频繁断线排查。
三家常见报错对照表
| 状态码 | OpenAI | Claude | Gemini | 先查什么 |
|---|---|---|---|---|
| 400 | 参数错误 | 请求格式错误 | 参数错误,或所在地区不支持 | 请求体、模型名、出口地区 |
| 401 | Key 无效 | 认证失败 | 多以 400 或 403 提示 Key 无效 | Key 和请求头 |
| 403 | 地区不支持或无权限 | 权限不足或地区限制 | 权限被拒绝 | 出口地区、项目权限 |
| 404 | 模型或路径不存在 | 资源不存在 | 模型或路径不存在 | 模型名拼写、接口路径 |
| 429 | 速率限制或额度不足 | 速率限制 | 资源耗尽 | 错误类型、账单与限额 |
| 5xx | 500、503 常见 | 500,过载时 529 | 500、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 应该只放在服务端或本地环境变量里,发现泄露要立即在控制台吊销并重新生成。