API 文档 · 排错手册
AI API 错误码速查手册
按 HTTP 状态码分层，对照 OpenAI、Claude、Gemini、DeepSeek 与中转站/网关的常见原因与修法。原则只有一条：保存 request ID，按错误类型（error.type）分支，而不是按错误文案——文案会变，类型稳定。
核验于 2026-09-04。具体行为随各家官方 API 版本变化，接入前请以官方文档与你的控制台为准。
通用 HTTP 状态码分层
四家 API 大体遵循同一套 HTTP 语义，先建立这张总表，再看各家差异。
| 状态码 | 含义 | 是否重试 | 第一步排查 |
|---|---|---|---|
| 400 | 请求体格式错误、参数非法 | 否 | 核对 JSON 结构与必填字段（如 Claude 的 max_tokens） |
| 401 | 鉴权失败：Key 错/缺失/撤销 | 否 | 检查鉴权头与 Key 状态，别循环重试 |
| 403 | 无权限：地区限制、模型未授权 | 否 | 确认账号/Key 是否有该模型权限、是否受地区限制 |
| 404 | 路径或模型 ID 不存在 | 否 | 核对 Base URL 是否多/少 /v1，model 名是否拼错 |
| 422 | 参数语义不合法（值超范围等） | 否 | 检查取值范围（temperature、max_tokens 上限等） |
| 429 | 限速或额度/余额不足 | 看情况 | 区分限速与欠费：限速退避重试，欠费先充值 |
| 500 | 服务端内部错误 | 是（有限） | 带抖动重试，保存 request ID 反馈 |
| 502/503/504 | 网关/上游不可达、过载、超时 | 是（有限） | 指数退避+熔断，检查是否上游故障 |
| 529 | 上游过载（Claude 常见） | 是（有限） | 带抖动限次重试 |
OpenAI / OpenAI 兼容
| 状态码 · error.type | 常见原因 | 修法 |
|---|---|---|
| 401 · invalid_api_key | Key 错误、缺少 Authorization: Bearer | 确认头为 Authorization: Bearer sk-...，核对 Key |
| 404 · model_not_found | 模型名拼错或账号无权限 | 用 /v1/models 列出可用模型，核对拼写 |
| 400 · context_length_exceeded | 输入+输出超模型上下文 | 压缩输入或分段；降低 max_tokens |
| 429 · rate_limit_exceeded | RPM/TPM 超限 | 指数退避+抖动，检查并发；读取 retry-after 头 |
| 429 · insufficient_quota | 额度用尽/欠费 | 重试无意义，充值或换项目 Key |
| 400 · invalid_request_error | 参数结构错、JSON mode 冲突 | 核对 messages 结构与 response_format |
迁移到 OpenAI 兼容接口的完整流程（契约冻结、影子验证、灰度回滚）见 OpenAI 兼容 API 迁移；接入基础见 OpenAI API 接入教程。
Claude（Anthropic Messages）
| 状态码 · type | 常见原因 | 修法 |
|---|---|---|
| 401 · authentication_error | 用了 Bearer 而非 x-api-key；Key 无效 | 改用 x-api-key + anthropic-version 头 |
| 400 · invalid_request_error | 缺 max_tokens（Claude 必填）、消息结构错 | 补齐 max_tokens 与 messages 结构 |
| 404 | Base URL 多带了 /v1（原生 SDK） | 原生 SDK 的 base_url 用主机根，不带 /v1 |
| 429 · rate_limit_error | 速率或额度限制 | 区分限速/欠费，限速带退避重试 |
| 529 · overloaded_error | 上游过载 | 带抖动限次重试 |
| 工具调用失败 | tool_use ID/参数/内容块顺序不匹配 | 检查 tool_use→tool_result 回传与 stop_reason=tool_use |
Claude 接入与鉴权、流式细节见 Claude 中转接入教程。
Gemini
| 状态码 · status | 常见原因 | 修法 |
|---|---|---|
| 400 · INVALID_ARGUMENT | 请求体字段错、模型名格式错 | 核对 model 路径（models/gemini-...）与字段 |
| 403 · PERMISSION_DENIED | API Key 无权限、地区限制 | 确认 Key 权限与可用地区 |
| 404 · NOT_FOUND | 模型 ID 不存在 | 核对当前可用模型 ID |
| 429 · RESOURCE_EXHAUSTED | 配额用尽或限速 | 退避重试或提高配额 |
| 500 · INTERNAL | 服务端错误 | 带抖动有限重试 |
Gemini 原生接口与 OpenAI 兼容层的双协议接入见 Gemini API 中转接入。
DeepSeek
| 状态码 | 常见原因 | 修法 |
|---|---|---|
| 401 | Key 无效 | 核对 Key 与 Authorization 头 |
| 402 | 余额不足 | 充值后重试（重试本身无意义） |
| 422 | 参数非法 | 检查参数取值范围与类型 |
| 429 | 请求过快 | 降并发、指数退避 |
| Base URL 混淆 | Endpoint 与 Base URL 写混 | 区分主机根与完整 endpoint |
DeepSeek 的 Base URL、模型与流式验证见 DeepSeek API 中转站接入。
中转站 / 网关特有情况
通过中转站或多模型网关时，错误可能来自网关本身，也可能是网关透传的上游错误。排查要先分清来源。
| 现象 | 可能原因 | 排查 |
|---|---|---|
| 502 / 503 / 504 | 网关到上游不可达/过载/超时 | 看是否上游故障；带熔断的有限重试 |
| curl 成功、SDK 失败 | Base URL 的 /v1 语义、SDK 默认路径差异 | 对齐 SDK base_url 与 curl 的完整路径 |
| 模型"支持"但工具调用失败 | 网关只实现了文本 Messages | 单独测工具协议，别用普通对话成功推断 |
| 用量对不上账 | 网关计量口径与上游不一致 | 保存网关与上游双 request ID 对账 |
中转站错误码的分层处理与脱敏诊断包见 API 中转站错误码排查；如何判断上游路由是否透明见 上游渠道核验。接入配置从 API 文档 开始。
常见问题
AI API 返回 401 应该怎么排查？
401 是鉴权失败。依次检查 Key 是否正确、是否被撤销或过期、鉴权头是否用对（OpenAI 用 Authorization: Bearer，Claude 用 x-api-key），以及请求主机是否正确。保存 request ID 后修复凭据再试，不要循环重试。
429 一定是被限速吗？
不一定。429 可能是速率限制（RPM/TPM）也可能是额度或余额不足。看响应体错误类型区分：限速可带指数退避有限重试，欠费重试无意义，应先充值或换 Key。
HTTP 200 之后还会出错吗？
会。流式响应在 HTTP 200 建立连接后，仍可能在 SSE 事件流中出现 error 事件或提前中断。必须消费完整事件链并等待结束事件（OpenAI 的 [DONE]、Claude 的 message_stop），再检查 finish_reason/stop_reason 与 usage。
通过中转站或网关时错误码有什么不同？
网关可能返回自身错误（502/503/504 表示上游不可达或超时），也可能透传上游错误。排查时区分错误来自网关还是上游，并保存网关与上游双 request ID 以便对账。
核验日期：本手册于 2026-09-04 复核。各家 API 的错误类型与行为会随版本调整，生产接入前请以官方文档与控制台实时信息为准。
不熟悉文中的概念？配合 AI API 术语表 一起看。