AI API 常见 401、429、500 排查思路
AI API 报错时，很多人第一反应是“模型挂了”或“中转站不稳定”。有时确实如此，但更多时候，错误来自身份、额度、限流、endpoint、代理或请求体格式。
排查时先不要急着换模型、换 key、换平台。先回答一个问题：这次失败发生在哪一层？
- 身份层：key、项目、组织、权限。
- 额度层：余额、quota、订阅、账单限制。
- 限流层：RPM、TPM、并发、队列、网关限流。
- 请求层：endpoint、model、参数、上下文长度。
- 网络层：DNS、代理、TLS、超时。
- 上游层：模型服务、区域服务、第三方供应商。
如果配置本身还没有检查过，可以先看 /zh/posts/ai-tool-config-checklist。
先收集最小证据
不要只截一张“请求失败”的图。至少保留这些信息：
- 发生时间。
- 工具或 SDK 版本。
base_url域名和路径。- endpoint，比如
/v1/responses、/v1/chat/completions、/v1/messages。 - model id。
- HTTP 状态码。
- 返回体里的
type、code、message。 - request id、trace id 或网关日志 id。
- 是否经过中转、公司网关或代理。
注意脱敏。不要贴完整 key、完整 prompt、cookie、session、JWT 或生产用户数据。
然后用最小请求复现：
只请求一句 hello，不带工具调用，不带长上下文，不带文件，不并发。
如果最小请求都失败，优先排查认证、endpoint、网络和额度。如果最小请求成功，真实任务失败，再看上下文长度、工具调用、输出格式、并发和模型能力。
401：先当成身份和权限问题
401 通常表示请求没有被正确认证。常见原因：
- key 写错、复制多了空格或换行。
- 工具没有读到你以为的 key。
- key 属于另一个平台，但你调用的是当前平台。
- key 被撤销、过期或项目被禁用。
- 账号有多个 organization、project 或 workspace，key 没挂到目标项目。
- 中转站 key 和官方 key 混用。
- 请求头格式错了，比如
Authorization: Bearer ...没带上。
排查顺序：
- 确认工具实际读取的 key 来源，不要只看
.env。 - 用同一个 key 发最小请求。
- 确认
base_url是这个 key 所属的平台。 - 确认 endpoint 与平台协议匹配。
- 去平台后台看 key 状态、项目状态和权限。
如果你通过中转站调用，上游 401 和中转站 401 要分开看。中转站返回的 401 可能是“你的中转 key 无效”；上游返回的 401 可能是“中转站到上游的 key 无效”。这两种问题的处理人不一样。
一个实用判断：如果同一个中转 key 调所有模型都 401，大概率是中转身份问题；如果只有某个上游模型 401，可能是该上游渠道配置或权限问题。
403：不是 401，但也常和权限有关
虽然标题只写 401、429、500，但实际排查时 403 也很常见。403 更像“身份已经识别，但不允许做这件事”。
常见原因：
- key 没有目标模型权限。
- 模型需要额外开通。
- 项目或组织没有通过对应安全、地区或账单条件。
- 网关策略拒绝了某类 endpoint。
- 公司代理或 WAF 拦截了请求。
403 不要只换 key。先确认“这个 key 是否应该能调用这个模型、这个 endpoint、这个区域”。
429：先分清额度不足还是限流
429 最容易被误解。它可能是“请求太快”，也可能是“额度不够”，还可能是中转站或公司网关自己的限流。
常见类型：
- 余额不足：账号没钱、套餐用完、项目 quota 到顶。
- 请求速率限制：每分钟请求数超过限制。
- token 速率限制：每分钟输入输出 token 过多。
- 并发限制：同时运行的请求太多。
- 队列限制：批量任务或 agent 任务排队太长。
- 网关限流：中转站、API 网关、代理或 WAF 限制。
排查时看错误体里的关键词。不同平台文案不同，但通常会出现 quota、rate limit、tokens per minute、requests per minute、insufficient balance、too many requests 之类的线索。
处理方式也不同：
- 额度不足：充值、换项目、降低模型成本、限制最大输出。
- RPM 超限：降低请求频率，加退避重试。
- TPM 超限：减少上下文、减少并发、限制输出 token。
- 并发超限：加队列，不要同时启动太多 agent。
- 网关限流：看网关日志和平台后台，不要只盯上游。
对 coding agent 来说，429 常常是上下文太大叠加并发导致的。一个 agent 读仓库、开工具、反复重试，很快就会把 token 速率打满。选模型和拆任务的方法可以看 /zh/posts/choose-model-for-coding-agent。
500：不要立刻认定是模型坏了
500 系列错误通常表示服务端失败，但“服务端”可能是很多层：
- 本地代理。
- 公司 API 网关。
- 中转站。
- 上游模型平台。
- 某个区域的模型服务。
- 某个 endpoint 的适配层。
先看返回体和响应头。如果有 request id 或 trace id，保留它。没有这些 id，后续让平台排查会困难很多。
常见原因：
- endpoint 和模型不匹配。
- 请求体字段被网关适配坏了。
- 上下文过长或输入格式触发服务端错误。
- 工具调用 schema 太复杂或不被支持。
- 上游临时故障。
- 中转站渠道切换失败。
- 代理超时被包装成 500。
排查顺序：
- 最小请求是否 500。
- 换同平台的轻量模型是否 500。
- 换 endpoint 是否 500。
- 不经过中转或网关是否 500。
- 降低上下文长度、关闭工具调用后是否恢复。
- 查看平台状态页或网关日志。
如果只有复杂请求 500，先缩小请求体。删除工具、删除长上下文、减少图片或文件、降低输出长度。能定位到“加上哪个部分就失败”，比单纯说“500 了”有价值。
区分错误来自哪里
同一个状态码，来源不同，含义不同。
你可以用这几个信号判断：
- 响应头里是否有上游 provider 的标识。
- 返回体里的错误格式像 OpenAI、Anthropic，还是网关自己的格式。
- 中转站后台是否有这次请求日志。
- 上游平台后台是否有这次请求记录。
- request id 是网关 id 还是上游 id。
- 不经过中转直连时是否复现。
如果中转站后台没有记录，请求可能根本没到中转：看本地网络、base_url、代理和 DNS。
如果中转站有记录，但上游没有记录，问题可能在中转鉴权、路由、渠道、请求适配或中转到上游的网络。
如果上游也有记录，问题更可能来自上游拒绝、限流、模型能力或请求体本身。
重试要克制
不是所有错误都该重试。
- 401：通常不要自动重试，先修 key。
- 403：不要盲目重试，先看权限。
- 429：可以退避重试，但要降低并发或 token。
- 500/502/503/504：可以有限重试，但要保留 request id。
- 超时：可以重试，但要判断是否已经产生费用或副作用。
对 agent 工具尤其要小心。agent 的一次“重试”可能重新读文件、重新调用工具、重新生成大段输出。没有退避和上限的重试，会把一个小故障扩大成额度问题。
一张简短排查表
| 状态码 | 先怀疑 | 第一件事 |
|---|---|---|
| 401 | key、项目、认证头 | 确认工具实际读取的 key 和 base_url 是否匹配 |
| 403 | 权限、模型开通、策略 | 确认 key 是否允许调用该模型和 endpoint |
| 429 | 额度、RPM、TPM、并发 | 判断是余额不足还是速率限制 |
| 500 | 网关、上游、请求体 | 用最小请求缩小范围，并保留 request id |
| 502/503/504 | 上游或代理链路 | 看网关日志、状态页和重试结果 |
AI API 排查的核心不是背状态码，而是先定位层级：身份、额度、限流、请求、网络还是上游。层级定位清楚，换 key、换模型、换平台才有意义。