指南/AI API 错误排查
429、5xx 和超时到底是谁的问题：AI API 错误排查手册
一次 429、502 或超时，不能直接证明官方上游宕机，也不能直接归咎于中转站。请求经过客户端、中转层和模型服务后，每一层都能拒绝、等待或改写响应；排查的任务，是确认错误最终由哪一层生成，以及请求走到了哪里。
状态码只标记最终响应的那一层
调用官方域名时，HTTP 响应通常来自官方 API。把 base_url 改成中转站后，客户端建立连接的对象变成中转站；中转站再发起另一条连接访问上游。此时客户端收到的 429 或 5xx，可能是中转站原样转发的，也可能由中转站自己的限流器、反向代理或应用生成。
HTTP 语义标准只定义响应码表达什么，不负责证明错误来自哪台服务器。例如 502 表示充当网关的服务器从上游收到无效响应，504 表示网关等待上游超时；两者都没有说明上游一定是 OpenAI、Anthropic 或 Google。
先把请求路径写清楚：
业务客户端 → 本地网络或公司代理 → 中转站入口 → 中转站应用 → 官方 API
任何一段都可能失败。没有请求记录时，只剩一条状态码，归因通常只能靠猜。
一次失败至少保留这些字段
排查记录要在重试前写下。重试成功会掩盖第一次失败的细节。
| 记录项 | 能回答什么 |
|---|---|
| 请求开始时间、结束时间、总耗时 | 错误是立即返回，还是等待到固定超时阈值后出现 |
| 访问的主机名、接口路径、模型名 | 当时请求打到哪个入口，是否混用了多个分组 |
| HTTP 状态码与完整错误体 | 是协议错误、限流、上游错误，还是中转站自定义文案 |
| 全部响应头 | 是否有 retry-after、额度余量与官方请求 ID |
| 首 Token 时间、中断前的 SSE 事件 | 连接前失败，还是已经开始生成后中断 |
| 客户端请求 ID 与本地任务 ID | 把业务日志、中转站日志和供应商支持记录对到同一次调用 |
OpenAI 建议在生产环境记录 x-request-id，并允许调用方发送自己的 X-Client-Request-Id；响应还可能带有速率限制余量与重置时间。OpenAI 的请求调试文档列出了这些响应头。Anthropic 的每个 API 响应带 request-id，错误体里也有相同的 request_id，官方错误文档要求联系支持时附上它。
中转站没有返回官方请求 ID，不足以证明请求没到上游，因为中间层可能没有转发该响应头。反过来，一个格式正确且可由供应商支持查询的请求 ID，是请求到达对应平台的强证据。
429：先区分谁的额度用完了
429 表示请求过密或额度受限，但限额可能设在多个位置：调用方账号、中转站账号、中转站为用户配置的本地额度，以及入口网关的防滥用规则。
三家官方平台的限流维度也不同。Anthropic 按请求、输入 Token 和输出 Token 等维度限流，429 会说明触发项并返回 retry-after；突增流量还可能触发加速限制，详见 Anthropic 速率限制。Gemini 的限额按项目而非单个 API Key 计算，常见维度包括每分钟请求、每分钟输入 Token 和每日请求，Gemini 速率限制以控制台显示的当前额度为准。OpenAI 也提醒短时突发可能在每分钟总量尚未用完时触发限制，处理 429 的官方说明建议使用指数退避。
排查顺序可以压成四步：
- 看错误体和响应头有没有供应商特有字段、触发的额度维度与
retry-after。 - 查同一中转站下其他模型、其他分组是否同时 429。只有一个用户或一个分组受影响，更接近本地额度或共享池问题。
- 有官方 Key 时，用同一模型发一条小型固定请求作对照。官方直连正常、中转站持续 429，只能把范围缩到中转侧；两边使用的项目和额度池不同，因此这仍不是定责证据。
- 看 429 在一分钟内的请求速率、输入 Token 速率和并发数上如何分布。单看日用量容易漏掉短时突发。
收到 retry-after 时按它等待；没有时再用带随机抖动的指数退避，并设置最大次数。无间隔重发会继续消耗部分平台的限流预算，还会把一次拥塞放大成重试风暴。
5xx：错误名比「服务器错误」更有用
5xx 要连同具体状态和错误类型看：
- 500 通常表示返回该响应的应用内部发生未预期错误。它可能来自官方应用，也可能来自中转站自己的协议转换代码。
- 502 表示网关从上游收到无效响应，常见于连接被重置、响应无法解析或协议转换失败。它能指向「网关与上游之间」，但不能单独指出上游身份。
- 503 表示当前服务不可用或暂时过载。Gemini 把
503 UNAVAILABLE归为服务暂时容量不足，见 Gemini 故障排查。 - 504 表示网关没有在期限内等到上游响应。期限由返回 504 的网关设置，未必等于模型服务的处理上限。
- Anthropic 还用 529
overloaded_error表达全局高流量下的暂时过载；这是 Anthropic 文档约定的状态，不是通用 HTTP 状态码。
如果中转站把所有上游错误统一改成 500，客户端就失去了最有用的分类信息。保留原始状态、错误体和官方请求 ID，是中转协议是否便于排查的一项硬指标。
超时：先找到计时器在哪
「超时」经常没有 HTTP 状态码。DNS 查询、TCP 连接、TLS 握手、等待首字节、两段流式事件之间的空闲时间，以及整个任务的总截止时间，都可以由不同计时器终止。
立即失败且没有 HTTP 响应，先查域名解析、证书、连接拒绝与客户端连接超时。总是在 30 秒或 60 秒附近中断，更像固定的客户端、负载均衡器或反向代理期限。已经收到首个 SSE 事件后中断，则要保存中断前的完整事件与流是否正常结束。
流式请求尤其容易误判。Anthropic 明确说明：SSE 已经返回 HTTP 200 后，流中仍可能出现 error 事件；高负载时可能收到 overloaded_error。Gemini API 错误文档也单列了 SSE 错误事件。只监控 HTTP 状态码，会把这类失败算成成功；完整的终止条件见流式响应返回 200，为什么仍然可能失败。
长输入还会同时影响超时与上下文判断。Gemini 文档把 504 的一个可能原因写成提示或上下文过大、无法在期限内完成；这不等于输入一定被截断。如何确认请求在哪一层变短，见上下文究竟在哪里被截断。
重试前先确认有没有副作用
模型推理多用 POST。按 RFC 9110 的幂等语义，客户端不能默认认为一次 POST 失败后安全重放。原请求可能已被模型服务接受，只是响应在返回途中丢失；重试可能重复计费，也可能让工具调用执行两次。
纯文本生成可以用业务任务 ID 去重，并在账单里核对是否出现重复调用。带写数据库、发消息、下单等工具的 agent，要把工具执行做成幂等操作，再允许自动重试。客户端请求 ID 适合关联日志，不应在文档没有承诺时当作供应商的去重键。
能下到什么结论
一条错误记录通常只能定位到某一段请求路径，不能证明运营方的动机。连续数据更有用：固定时段集中出现 429，先查共享额度与并发；首 Token 时间逐日升高后出现 504，先查容量和网关期限；HTTP 200 增多但 SSE 完成事件减少，则要把流中错误单独计数。
错误排查的交付物应是一组可复核的时间、字段和对照请求。证据齐全后，再讨论是谁的问题。
LinkyMonitor 连续记录状态码、延迟、首 Token 时间与响应特征，便于区分短时波动、固定时段拥塞和配置变更。