# AI API 通用错误码与排障指南 处理 AI API 错误时应同时解析 HTTP 状态、厂商业务码、错误类型、消息、重试提示和请求 ID；参数、鉴权、余额与硬配额错误先修复根因，只有临时限流、网络错误和确认属于瞬时故障的部分 5xx 才适合有限重试。 ## 先分开 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： ```text http_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 是否已经自动重试；配置熔断、降级模型和告警，避免故障期间形成重试风暴。 - 异步创建使用业务幂等键；超时后先查询，无法确认结果时转人工或补偿流程，不盲目重复计费操作。 ## 最小复现与升级支持 先用 [快速入门](https://api.tu-zi.com/docs/use-cases/getting-started) 的最小 curl 验证同一 Base URL、本站密钥、端点和模型，再逐项加回媒体、工具和可选参数。若 curl 成功而 SDK 失败，记录 SDK 的脱敏有效 URL、版本、代理、超时和重试配置；若最小 curl 也失败，携带请求 ID、时间、路径、模型、状态码和业务错误对象联系支持。 ## 适用场景 - 排查首次调用失败 - 设计生产重试、熔断与降级 - 向平台支持提供可定位证据 ## API 路径 - /v1/chat/completions - /v1/responses - /v1/messages - /v1beta/models/{model}:generateContent - /v1beta/models/{model}:streamGenerateContent ## 关联指南 - [AI API 快速入门：从 API Key 到第一次调用](https://api.tu-zi.com/docs/use-cases/getting-started): 调用 AI API 需要匹配的 Base URL、API Key、模型名和端点；先用最小 curl 请求跑通，再处理错误、费用与密钥安全。 - [OpenAI 兼容 API 调用指南](https://api.tu-zi.com/docs/api/openai): 本站 OpenAI 兼容接口使用 Bearer 令牌；Responses、Chat Completions 与媒体端点拥有不同对象和流式语义，需按目标模型选择。 - [Anthropic Messages API 调用指南](https://api.tu-zi.com/docs/api/anthropic): Messages API 使用 system、角色消息和内容块；直连 Anthropic 要求 `x-api-key` 与版本头，本站推荐统一 Bearer，同时兼容原生 `x-api-key`。 - [Gemini API 调用指南：GenerateContent、Live 与 Interactions](https://api.tu-zi.com/docs/api/gemini): 本站提供 GenerateContent 与 gemini-3.8-live 的 /v1beta/live 原生 WebSocket；Live 使用 setup 与 serverContent 协议，只支持语音输出，可开启配套转写。 ## 常见问题 ### 429 一定是请求太快吗？ 不一定。OpenAI、Kimi、智谱、百炼、Azure 和 Cloudflare 等平台还会用 429 表示余额、套餐、日配额、并发或平台容量问题。必须结合业务码、错误类型、消息和重试 Header 判断；只有临时限流或容量错误适合退避重试。 ### 400、413 和 422 有什么区别？ 400 通常是格式、字段或模型能力不匹配；413 是整个 HTTP 请求体字节数过大；422 表示请求可解析但参数语义无效。三者都应先修改请求，原样自动重试通常无效。 ### 500、502、503、504 与 529 都能重试吗？ 不能一概而论。过载、网关和临时服务故障可有限退避，但部分 500/504 也可能由确定性输入问题触发；529 是 Anthropic 的临时过载。先读厂商业务码与消息，并确保操作幂等或可安全去重。 ### HTTP 200 但没有文本，算成功吗？ 不一定。流式连接可在 200 后发送错误事件，GenerateContent 可能通过安全反馈或 finish reason 表示拦截，腾讯云原生协议还可能在 HTTP 200 的响应体中返回业务错误。只有收到协议定义的完成状态才算成功。 ### 内容安全错误可以自动重试吗？ 不应原样重试。先读取 content_filter、safety、ResponsibleAIPolicyViolation 或厂商安全业务码，修改输入、图片或业务流程后再提交；对同一内容做指数退避既无效，也可能放大费用和审核压力。 ### 为什么排障时必须保存 request ID？ 它能把客户端错误关联到本站和厂商日志。本站响应头使用 X-Oneapi-Request-Id；厂商可能使用 x-request-id、request-id、apim-request-id、x-amzn-requestid 或响应体 request_id。升级支持时同时提供 UTC 时间、路径、模型与脱敏错误对象。 ### 客户端超时是否代表模型没有执行？ 不能这样判断。客户端断开不等于上游取消；图片、视频、Batch 或其他有副作用的提交超时后，应先按任务 ID、请求 ID 或业务幂等键查询，避免重复创建和重复计费。 ### curl 成功但 SDK 失败，先检查什么？ 比较 SDK 实际使用的 Base URL、路径、代理、模型名、API 版本和请求 JSON，再检查 SDK 版本、默认超时、自动重试与环境变量。官方 SDK 可能已经重试，应用层叠加重试会放大流量。 ## 参考来源 - OpenAI Error Codes: https://developers.openai.com/api/docs/guides/error-codes - OpenAI Rate Limits: https://developers.openai.com/api/docs/guides/rate-limits - Claude API Errors: https://platform.claude.com/docs/en/api/errors - Gemini API Errors: https://ai.google.dev/gemini-api/docs/api-errors - Gemini API Troubleshooting: https://ai.google.dev/gemini-api/docs/troubleshooting - DeepSeek Error Codes: https://api-docs.deepseek.com/quick_start/error_codes - 阿里云百炼错误码: https://help.aliyun.com/zh/model-studio/error-code/ - Kimi API 错误说明: https://platform.kimi.com/docs/api/errors - 智谱 API 错误码: https://docs.bigmodel.cn/cn/api/api-code - 百度千帆错误码: https://cloud.baidu.com/doc/qianfan-api/s/Om9b4yj3w - 腾讯混元错误码: https://cloud.tencent.com/document/product/1729/101847 - Amazon Bedrock API 错误排查: https://docs.aws.amazon.com/bedrock/latest/userguide/troubleshooting-api-error-codes.html - Azure OpenAI 配额与 429: https://learn.microsoft.com/en-us/azure/foundry/openai/how-to/quota - Cloudflare Workers AI Errors: https://developers.cloudflare.com/workers-ai/platform/errors/ - Mistral Error Glossary: https://docs.mistral.ai/resources/error-glossary ## 文档来源 来源: https://api.tu-zi.com/docs/use-cases/troubleshooting 核验日期: 2026-08-08 本文为文档接入参考。厂商原生接口与本站接口可能不同；请结合对应 API Reference 和模型广场确认本站地址、鉴权、模型 ID、分组与参数。本文不表示所有模型或上游服务均已通过实时调用验收。仅包含文档与示例，不包含当前用户的密钥或请求记录。