AI API 通用错误码与排障指南

先分开 HTTP 状态与厂商业务码

HTTP 状态只说明失败的大类，不能直接决定根因或重试。一次错误至少要读取：HTTP 状态、厂商 type/code/status、消息、相关参数、重试 Header 和请求 ID。OpenAI 风格错误常见 error.type/code/param/message；Anthropic 使用顶层 request_id 与嵌套 error.type/message；Gemini Interactions 的 error.code 是字符串，而 GenerateContent 使用数字 code、字符串 status 和可选 details。腾讯云原生 API 3.0 业务失败时还可能保持 HTTP 200，必须检查 Response.Error.Code。

建议把不同厂商响应归一化到日志字段，不要伪造一套“所有厂商都支持”的上游 JSON：

Copyhttp_status=429
provider_error_type=rate_limit_error
provider_error_code=rate_limit_exceeded
gateway_request_id=...
provider_request_id=...
retry_after=2s
attempt=1

通用错误码速查

• 400 Bad Request：JSON、必填字段、参数范围、上下文、模型能力或内容安全校验失败。先按消息修请求，不原样重试。
• 401 Unauthorized：密钥缺失、无效、过期、撤销或签名失败。修复认证后再发。
• 402 Payment Required：Anthropic、DeepSeek 等用于账单或余额问题。充值或修复付款信息前重试无效。
• 403 Forbidden：凭证可能有效，但缺少模型、区域、资源或账户权限，也可能未接受模型协议。先授权或换正确资源。
• 404 Not Found：域名、路径、API 版本、部署名、模型或任务不存在。注意展示名、原生模型 ID、云部署名和本站别名并不等价。
• 405 Method Not Allowed 与 415 Unsupported Media Type：先核对 HTTP 方法、端点和 Content-Type；部分平台也会把不支持的 SDK 或模型能力映射到 405，所以仍要读业务码。
• 408 Request Timeout：请求或模型处理超时；499 Client Closed Request 表示客户端取消或断开。执行结果可能未知，先查任务状态再决定是否重试。
• 409 Conflict：资源并发更新、重复创建或状态冲突。刷新状态、解决冲突后再试。
• 413 Payload Too Large：HTTP 请求体字节数超限，常见于 Base64 媒体；压缩、缩放、分片或改用目标端点明确支持的文件引用。
• 422 Unprocessable Entity：请求可解析但参数语义无效，DeepSeek、Mistral 等会使用；修改字段组合后再发。
• 424 Failed Dependency：上游模型或依赖失败，Amazon Bedrock 的 ModelErrorException 是代表性用法；先看原始状态和资源名，不应把所有 424 一律重试。
• 429 Too Many Requests：可能是 RPM、TPM、并发、突发流量、余额、套餐、日配额、免费额度或平台容量；必须继续按业务码分类。
• 500 Internal Server Error：厂商内部错误，也可能掩盖输入边界问题；保留原始错误，只对确认的瞬时故障有限重试。
• 502 Bad Gateway、503 Service Unavailable、504 Gateway Timeout：网关、区域容量、上游不可用或处理超时。持续失败时应降速、熔断、切换已验证的区域/模型或检查状态页。
• 529 Overloaded：Anthropic 明确用于临时全局过载；流式场景可能在已返回 200 后以 overloaded_error 事件出现。

429 必须按业务码再分类

临时速率限制可遵循 Retry-After；Azure 还可能返回毫秒级 retry-after-ms。Header 缺失时，可使用带随机抖动的指数退避并限制最大次数与总时长。失败请求也可能计入限额，热循环只会让恢复更慢。

余额不足、套餐过期、消费上限、日配额或免费额度耗尽需要充值、续订、提额或等待重置，不能靠快速重试恢复。代表性差异包括：DeepSeek 用 402 表示余额不足；Kimi 把过载、余额和 RPM/TPM 都放在 429 下；智谱在 429 下用不同业务码区分欠费、账户限流、模型拥挤和套餐上限；Cloudflare 的 3036 是免费 Neurons 用尽，3040 是无可用数据中心。生产逻辑必须匹配稳定业务码，不能匹配可能改写或本地化的 message。

厂商协议差异

• OpenAI：保留 error.type 与 error.code；429 要区分临时限流和余额/组织或项目消费上限。官方 SDK 默认会重试连接错误、408、409、429 与 5xx，应用层不要无意叠加。
• Anthropic：除常见码外还定义 402、409 与 529；每个响应有 request-id，错误体也有 request_id。错误类型和流事件可能扩展，解析器应容忍未知值。
• Gemini：Interactions 与 GenerateContent 是两套错误模型，不能混用字段。Interactions 把 rate_limit_exceeded 与 quota_exceeded 分开；GenerateContent 的安全拦截、停止原因或无候选结果可能不是 HTTP 错误。
• 百炼、Kimi、智谱与百度千帆：普遍同时使用 HTTP 状态和更细业务码；同一个 400 或 429 可能分别表示参数、安全、余额、套餐、硬配额或临时拥挤。百炼原生响应常带 request_id，但不能据此假设所有兼容端点结构完全相同。
• 腾讯混元原生协议：服务端正常处理后常返回 HTTP 200，业务错误位于 Response.Error.Code；判断必须依赖稳定 Code，不能依赖可能变化的 Message。
• Amazon Bedrock：SDK 暴露 ValidationException、ModelTimeoutException、ModelErrorException、ThrottlingException 等异常名；424、429 和 503 的根因不同。
• Azure OpenAI：429 可能是部署 TPM/RPM，也可能是临时容量；优先读取 retry-after-ms 与 x-ratelimit-*。内容策略信号不能当作临时 400 重试。
• Cloudflare Workers AI 与 Mistral：Cloudflare 需要结合内部数字码判断免费额度或容量；Mistral 将 429/500/502/503/504 归为可退避的瞬时错误，但请求、认证和权限错误仍须先修复。

HTTP 200 后仍可能失败

SSE 或 NDJSON 一旦开始传输，HTTP 状态通常不能再改变。OpenAI Responses、Anthropic Messages 和 Gemini Interactions 都可能在流中发送错误事件；Gemini GenerateContent 还要检查 promptFeedback、候选项 finishReason 和是否存在候选结果。异步图片、视频与 Batch 的 200/202 只表示受理，最终任务仍可能失败。

客户端必须按协议边界解析完整事件，容忍未知事件类型，并只在收到明确完成事件或终态后标记成功。流中断后不要自动重放已产生副作用或可能计费的创建请求；先用任务 ID、幂等键和日志确认上游状态。

保存请求 ID 与最小证据

本站每次响应使用 X-Oneapi-Request-Id；请同时保存厂商返回的 x-request-id、request-id、apim-request-id、x-amzn-requestid 或响应体 request_id/RequestId（存在时）。不要把异步任务 ID 当成所有同步请求的追踪 ID，也不要假设每家厂商都提供相同 Header。

一次可定位的失败至少包含：UTC 时间、本站请求 ID、厂商请求 ID、路径、模型、HTTP 状态、业务码、是否流式、尝试次数和耗时。密钥只保留少量掩码，正文、文件与个人数据按最小必要原则采集；工单中不要发送完整密钥或敏感输入。

生产重试与降级规则

• 默认不自动重试 400/401/402/403/404/405/413/415/422、内容安全、余额、套餐和硬配额错误；根因修复后再发。
• 409 先刷新状态并解决冲突；408/499 先判断是否已执行，只有幂等或可安全去重的操作才重试。
• 临时 429、网络错误与确认属于瞬时故障的 500/502/503/504/529 使用有界指数退避、随机抖动、总截止时间和并发上限。
• 优先遵守有效的 Retry-After，同时检查 SDK 是否已经自动重试；配置熔断、降级模型和告警，避免故障期间形成重试风暴。
• 异步创建使用业务幂等键；超时后先查询，无法确认结果时转人工或补偿流程，不盲目重复计费操作。

最小复现与升级支持

先用 快速入门 的最小 curl 验证同一 Base URL、本站密钥、端点和模型，再逐项加回媒体、工具和可选参数。若 curl 成功而 SDK 失败，记录 SDK 的脱敏有效 URL、版本、代理、超时和重试配置；若最小 curl 也失败，携带请求 ID、时间、路径、模型、状态码和业务错误对象联系支持。