API 中转站错误码：400、401、404、422、429 与 5xx 排查
API 中转站错误码如何排查？分层处理 400、401、404、422、429、502、503、504，保存请求 ID 并生成脱敏诊断包。
排查 API 中转站错误时，状态码只用于分流，先保存脱敏证据，再定位客户端、网关或上游，检查是否已经输出或产生副作用，最后才决定修复、等待、有限重试或回退。
- 本页：按状态码分层的排查流程。只有 400、401、429、5xx 这类状态码，或要定排查顺序、写脱敏诊断包时看。
- 按报错原文查：SSE stream ended without [DONE]、Invalid API key 等：手上有一句报错原文时，直接按原文找对应小节。
- AI API 错误码速查表：按状态码对照 OpenAI、Claude、Gemini、DeepSeek 和网关的常见原因与修法。
错误码决策表
| 状态 | 语义/常见层 | 第一动作 | 自动重试 |
|---|---|---|---|
| 400 / 422 | 请求语法或语义 | 修复请求 | 否 |
| 401 / 403 | 鉴权或权限 | 核对 key、项目和策略 | 否 |
| 402 | 额度/计费条件 | 停止并核账 | 否 |
| 404 | 最终 URL、端点族或模型 | 保存 URL 后逐项核对 | 否 |
| 429 | 速率、配额、容量或网关策略 | 读错误类型与 Retry-After | 有条件且有上限 |
| 500 | 服务器内部失败 | 保存 ID，判断副作用 | 有条件 |
| 502 | 网关收到无效上游响应 | 查上游连接/响应 | 有条件 |
| 503 | 服务暂不可用 | 遵循有效等待提示 | 有条件 |
| 504 | 网关等待上游超时 | 查各段超时与状态 | 有条件 |
RFC 9110 分别定义了 502、503、504，不能把它们都写成“服务器坏了”；RFC 6585 定义 429，并允许服务器提供 Retry-After，但余额或硬配额并不会靠等待恢复。
生成最小脱敏诊断包
export RELAY_BASE_URL="https://relay.example/v1"
export TEST_KEY="replace-with-lab-key"
export MODEL_ID="replace-with-model-id"
curl -sS -D response-headers.txt -o response-body.json "$RELAY_BASE_URL/chat/completions" -H "Authorization: Bearer $TEST_KEY" -H "Content-Type: application/json" -H "X-Client-Request-Id: lab-case-001" --data "{\"model\":\"$MODEL_ID\",\"messages\":[{\"role\":\"user\",\"content\":\"Reply: ok\"}],\"max_tokens\":8}"
grep -iE "^(HTTP/|retry-after:|x-request-id:|request-id:)" response-headers.txt诊断包记录时间、最终 URL、method、模型、客户端 request ID、网关/上游请求 ID、status、脱敏 error type、retry_after_ms、剩余截止时间、幂等键是否存在、stream/tool 状态与 trace ID；排除 Authorization、Cookie、完整 prompt 和输出。
故障定位路径：客户端 → 网关 → 上游
- 客户端：打印最终 URL，验证 JSON、Content-Type、超时、SDK 是否重复追加
/v1。 - 网关：核对鉴权、余额、项目权限、路由和网关请求 ID。
- 上游：保留上游错误类型、request ID、Retry-After 与流状态，不把所有错误压成统一 500。
- 业务状态：若已见首个流事件或工具开始，先核对副作用再决定是否重放。
需要完整测试前置条件时看API 中转站检测；流式事件边界见流式与工具调用兼容性。
处理后的校验清单
- 错误码、机器错误类型与最终 URL 均已保存。
- 401/403 修复凭据或权限后才重放；400/422 修复请求后才重放。
- 429 已区分余额、速率、容量和网关策略，并限制等待上限。
- 5xx/超时已检查幂等、流状态、副作用和剩余 deadline。
- 每次上游尝试有独立 attempt ID，能连接到根 trace。
- 脱敏诊断包不含 key、Cookie、完整输入输出或个人信息。
OpenAI 建议保留 x-request-id，并允许客户端提供 X-Client-Request-Id；Anthropic 文档说明响应含 request-id。兼容中转不一定透传这些厂商头，因此缺失时仍要使用自己的 trace/request ID。
常见错误与误读
- 无限重试 401、404 或参数错误。
- 认为所有 429 都能等待恢复，忽略余额与硬配额。
- 把 502、503、504 当成同一根因。
- 只看 HTTP 200，忽略 SSE 在开始后失败。
- 把 request ID 当作去重幂等键，导致重复工具副作用。
重试门禁与预算详见API 重试机制，跨层关联见API 中转站可观测性。本文不保证所有兼容服务使用相同错误 JSON、响应头、计费或可重试集合。
429、5xx 与部分成功的复核分支
处理 429 时先解析机器错误类型，再检查有效的 Retry-After。速率限制可通过降低并发、请求速率或 Token 速率缓解；余额、消费上限和权限策略应停止并交给账户流程；容量型错误是否重试仍受幂等和 deadline 约束。若响应头与错误体给出冲突等待值，保留两者并按客户端安全上限处理，不无限等待。
处理 5xx 时把“网关生成”与“上游返回”分开。502 重点看连接建立、TLS、上游响应格式和网关解析；503 重点看维护、过载、熔断与路由可用性；504 重点比较客户端总超时、网关上游超时和上游实际完成状态。错误页或非 JSON 正文也必须作为脱敏证据保存，不能因解析失败而丢失 status 和 headers。
所谓部分成功包括：HTTP 200 后 SSE error、收到文本但缺少结束事件、工具调用参数已发出但结果未知、网关返回成功而结算异步失败。此时不要把记录归入完整成功，也不要无条件归入普通 5xx。保存 stream_state、最后事件类型、可见字符数类别、tool_state、usage 是否出现与连接断开方，再由业务层决定继续、补偿或提示用户。客户端把缺少结束事件报成 SSE stream ended without [DONE] 时，四种成因和确认命令见sse stream ended without [DONE] 的成因与确认命令。
升级诊断包前做二次脱敏：Authorization/Cookie 删除，key 只保留不可逆且受控的项目别名，URL 查询串过滤，prompt/output 用长度与哈希类别替代，错误正文只保留白名单字段。诊断包附复现命令模板、时间窗口、时区、请求 ID 列表和“是否允许安全重放”的判断，支持端到端复核而不泄露业务内容。
请求、响应与参数边界验收表
错误排查必须同时保存请求边界与响应边界：前者是最终 URL、方法、模型、Content-Type、请求体 schema、超时、重试状态和幂等上下文；后者是状态码、机器错误类型、Retry-After、脱敏请求 ID、流状态、工具状态和响应体摘要。参数边界尤其要标明 SDK 是否自动追加版本路径、代理是否改写头、最大等待和剩余 deadline。
| 故障分支 | 请求/参数证据 | 响应证据 | 失败模式 | 验证指标与恢复 |
|---|---|---|---|---|
| 401/403/404 | 最终 URL、鉴权头存在性、端点族、模型 | 状态、错误类型、request ID | 凭据失效、权限拒绝、路径重复、模型映射缺失 | 修复后只重放一条无副作用请求；同错误不循环重试 |
| 429 | 并发、发送速率、额度状态、deadline | Retry-After 与机器错误类型 | 速率、并发、余额、容量或网关策略被混写 | 按子类型计数；余额问题停止，限流才受限退避 |
| 5xx / 部分流 | 幂等键、stream_state、tool_state、剩余预算 | 502/503/504、最后事件、attempt ID | 重复副作用、200 后中断、上游状态未知 | 先 reconcile；可安全重复时才有限恢复 |
“API 中转站 404 模型不存在怎么办”不能只看一条消息，应核对 Base URL、SDK 自动路径、端点族和模型目录。OpenAI 兼容 API 的私有错误体不是通用标准，API 404 错误与 API 请求 ID 的字段名也以实际版本为准。若诊断包误含 Authorization、Cookie、prompt 或输出正文，立即停止共享，删除派生副本并从脱敏模板重新生成。
一手资料
停止、回滚与恢复步骤
若诊断命令使用了错误端点、真实写入工具、未脱敏日志或未知副作用，立即停止重试并撤销测试 key。冻结请求头和错误体副本，先删除凭据与 Cookie，再共享诊断包。配置回滚到最后一个已知可用的 Base URL、端点族和请求 schema；修复 400/401/404 后只发一条无副作用短请求。恢复 429/5xx 流量前确认 Retry-After、deadline、幂等和流状态，逐步解除限流，并核对没有重复工具调用或重复结算。
执行问题与参数边界
以下回答用于定位常见执行问题。实际判断仍需结合本文的参数、失败模式和验证指标，不应仅凭一项现象推断服务能力。
API 中转站 401 错误怎么排查
API 401 错误先查 key、鉴权头、项目和模型权限。
API 中转站 429 限流怎么处理
API 429 错误要区分速率、配额、余额与容量。
API 502 503 504 区别
API 502 错误、API 503 错误与 API 504 错误按 RFC 分开定位。
API 返回 200 但流式响应失败怎么办
保存最后事件、请求 ID、完成标记与副作用状态。
API 错误日志需要记录什么
HTTP 错误码、最终 URL、错误类型、时间与脱敏 request ID 都要记录。
API request id 在哪里查看
先查响应头和 SDK 顶层字段，再用自有 trace 关联。
常见问题
API 中转站 401 错误怎么排查？
检查密钥是否存在或被撤销、Authorization 格式、项目与模型权限；修复前不要自动重试同一凭据。
404 一定表示模型不存在吗？
不一定。先保存最终 URL，再核对 Base URL、SDK 自动追加的版本路径、端点族、模型 ID 和网关是否实现该资源。
API 中转站 429 应该等待多久？
优先使用有效且受本地上限约束的 Retry-After；否则在总截止时间内退避并降低并发。余额或硬配额错误应停止而不是等待。
API 502、503、504 有什么区别？
502 是网关收到无效上游响应，503 是服务暂不可用，504 是网关未及时收到上游响应；都要结合请求 ID、流状态、幂等和剩余预算决定动作。
