API 与错误码
错误码与限流
每个错误码对应的确切下一步 —— 它们都不是「服务坏了」。
接入期遇到的失败绝大多数都在下面这张表里。它们都不属于「服务坏了」， 每一条都有明确的下一步。
| 错误码 | 含义 | 怎么办 |
|---|---|---|
| invalid_api_key | 密钥无效 | 检查是否被吊销 / 复制完整；若此密钥配了 IP 白名单，从别处调用看到的也是这一句 —— 先确认来源 IP |
| insufficient_balance | 余额不足 | 去充值 |
| account_overdrawn | 余额为负，通常是退款扣回 | 联系客服核对账务 |
| budget_exceeded | 此密钥已达预算上限 | 调整预算或换一把密钥 |
| model_not_allowed | 该密钥不能调这个模型 | 看 message：「…by your plan」= 升级套餐；「…for this API key」= 套餐是够的，联系客服放宽这把密钥 |
| rate_limit_exceeded | 请求过快 | 按 Retry-After 退避 |
| no_available_channel | 该模型暂时不可用 | 稍后重试 |
| upstream_error | 上游返回了错误 —— 不是你的请求写错了 | 先换一个模型试试；这类问题要我们去接上游，改请求没有用。持续出现请带 request_id 提工单 |
| system_not_supported_upstream | 该模型当前的上游都会丢弃 system 提示词 | 去掉 system 后重试即可通过；或在模型广场挑一个没有「不支持 system」标记的模型 |
| context_length_exceeded | 输入长度超过该模型在本平台声明的上下文上限 | 缩短输入或分段发送；换一个上下文更大的模型也可以。重试无效，报错里带着实际长度和上限 |
| tenant_closing | 账号正在注销 | 联系客服，充值不会恢复 |
走 /v1/messages 时是另一套错误类型
Anthropic 原生协议有它自己的一套错误类型（响应体里的 error.type），
与上面那张表不通用 —— SDK 读的就是它。
| error.type | HTTP | 含义 | 怎么办 |
|---|---|---|---|
| authentication_error | 401 | 密钥无效 | 检查是否被吊销 / 复制完整；配了 IP 白名单时，从别处调用看到的也是这一句 |
| permission_error | 403 | 套餐或密钥不允许这个模型，或账号正在注销 | 看 message：写的是模型不允许就去调整密钥的模型范围或升级套餐；写的是账号状态就联系客服 |
| not_found_error | 404 | 这个模型不在 /v1/messages 上（它没有配 Anthropic 上游） | 换一个模型，或改走 /v1/chat/completions —— message 里会指路。重试没有意义 |
| request_too_large | 413 | 请求体过大 | 压缩或拆分（多模态内容通常是大头） |
| rate_limit_error | 429 | 限流 / 配额用尽 / 余额不足 / 密钥预算到顶（四种共用这一个类型） | 先看余额，再看 message —— 写明是账务限制的，重试没用；确实是限流的才按退避重试 |
| api_error | 502 / 504 | 上游全部失败，或到点被硬中止 | 稍后重试；反复出现就带 request_id 开工单 |
| overloaded_error | 503 | 这个模型此刻没有可用上游（冷却或受限），不是「没有这个模型」 | 按响应里的 Retry-After 退避重试 —— 这是暂时的 |
⚠️ 最容易误判的是 rate_limit_error：余额不足在这套协议里也报它
（Anthropic 协议里没有「余额不足」这个类型）。收到 429 先看余额，
message 里会写明是不是账务限制 —— 是账务限制的话，重试多少次都不会好。
限流怎么退避
收到 rate_limit_exceeded 时，响应里会带 Retry-After（秒）。
按它退避，不要固定间隔重试 —— 固定间隔在高峰期会让你和自己抢配额。
建议指数退避 + 抖动，上限取 Retry-After 与你自己的超时中较大的那个。
报障要带 request_id
每个响应都带 request_id。没有它我们查不到那一笔 ——
网关每天的调用量很大，靠「大概十点多的那次」是定位不到的。
开工单时贴上：request_id、发生时间、用的模型、完整的错误响应体。
一类特别容易误判的情况
insufficient_balance（余额不足）和 account_overdrawn（余额为负）不是同一件事：
- 余额不足：余额还是正的，只是不够这一笔。充值确实能解决。
- 余额为负：多半是一笔退款扣回把余额扣穿了。再充值也解决不了根因， 应该开工单让客服核对账务。
这两条以前是合成一行的，结果就是被扣穿的客户一直在充值，而账务上真正出的问题没人看。