API 与错误码
错误码与限流
每个错误码对应的确切下一步 —— 它们都不是「服务坏了」。
更新于 2026-08-17
接入期遇到的失败绝大多数都在下面这张表里。它们都不属于「服务坏了」， 每一条都有明确的下一步。
| 错误码 | 含义 | 怎么办 |
|---|---|---|
| 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 | 该模型暂时不可用 | 稍后重试 |
| tenant_closing | 账号正在注销 | 联系客服，充值不会恢复 |
限流怎么退避
收到 rate_limit_exceeded 时，响应里会带 Retry-After（秒）。
按它退避，不要固定间隔重试 —— 固定间隔在高峰期会让你和自己抢配额。
建议指数退避 + 抖动，上限取 Retry-After 与你自己的超时中较大的那个。
报障要带 request_id
每个响应都带 request_id。没有它我们查不到那一笔 ——
网关每天的调用量很大，靠「大概十点多的那次」是定位不到的。
开工单时贴上：request_id、发生时间、用的模型、完整的错误响应体。
一类特别容易误判的情况
insufficient_balance（余额不足）和 account_overdrawn（余额为负）不是同一件事：
- 余额不足：余额还是正的，只是不够这一笔。充值确实能解决。
- 余额为负：多半是一笔退款扣回把余额扣穿了。再充值也解决不了根因， 应该开工单让客服核对账务。
这两条以前是合成一行的，结果就是被扣穿的客户一直在充值，而账务上真正出的问题没人看。