状态码能背下来，但响应体里那串英文 code 和提示语经常看不懂，只能猜是 Key 错了还是余额没了还是模型名写错了。这篇按 error code 文本做成速查表：每条给一句人话意思、一个先动手查的位置、以及到底该不该重试，遇到拿不准的就顺着排查顺序往下走。
状态码能背下来，但响应体里那串英文 code 和提示语经常看不懂，只能猜是 Key 错了、余额没了，还是模型名写错了。这篇按 error code 文本做成速查表：每条给一句人话意思、一个先动手查的位置、以及到底该不该重试。
遇到拿不准的，就顺着后面的排查顺序往下走，先把不用重试的那几类排掉。如果你已经能从状态码判断出大概方向，可以把它当成细粒度补充；状态码层面的粗分类，去 按状态码写的报错篇（/guides/http-status-code） 对照看更省事。
先分清三层：HTTP 状态码、error code、人话提示
一个错误响应里通常有三层信息。状态码是粗分类，负责回答「这是谁的责任、要不要重试」；error code 才指向具体原因；message 往往只是给人看的措辞。只盯状态码，你会知道「大概跟额度有关」，但不知道到底是欠费还是套餐没生效。
| 层次 | 看什么 | 回答什么问题 |
|---|---|---|
| HTTP 状态码 | 2xx / 4xx / 5xx | 责任方与是否可重试 |
| error code | 如 invalid_api_key 这类字符串 | 具体原因指向哪一类 |
| message | 英文或中文提示语 | 补充细节，措辞不保证统一 |
- 同一句提示在不同中转站的措辞可能不一样，认关键词而不是认整句原文
- 先看响应体里的 code 与 type 字段，再看 message，最后才回头看状态码，顺序反过来容易误判
- 拿不准时把完整响应体复制下来，别只截状态码去问客服
- 中转站可能改写或隐藏上游 error code，遇到 code 为空时以状态码和返回结构为主
速查表上半：Key、权限、模型名这三类
这一类的共同点：基本都是配置问题，反复重试不会有任何变化，只会白白消耗时间。先把「先查哪里」做掉，改完再请求一次就够了。
| code / 提示关键词 | 人话意思 | 先查哪里 | 要不要重试 |
|---|---|---|---|
| invalid_api_key | Key 不存在或写错 | 查复制时是否带空格、换行、引号，前缀是否写错 | 不要 |
| permission / forbidden 类 | Key 有效但没这个模型的权限 | 查账户权限与渠道分组说明 | 不要 |
| model_not_found | 模型名拼错，或该渠道没这个模型 | 去 /models 核对准确名称，再看渠道说明 | 不要 |
| account_deactivated / organization 类 | 账户状态异常 | 人工处理通道，别继续打接口 | 不要 |
- 确认 Key 的原始形态把环境变量里的值原样打印出来（别打印到公开日志），看首尾有没有空白字符，再看前缀对不对。改完只请求一次验证。
- 核对模型名用 /models 类接口列出可用名称，逐字比对大小写和分隔符；中转站还要看它自己声明的渠道与分组，同名模型未必都在转发。
- 看权限说明部分模型需要单独开通或属于某个渠道分组，去站内 中转站目录（/sites） 对应条目的说明页核对它到底转发了哪些模型。
速查表下半：额度、限流、长度、超时这四类
这一类跟上一类正好相反：有些能靠重试解决，有些必须先改内容，混在一起盲刷是最常见的浪费。判断标准是「重试前条件有没有变化」——条件没变，重试就没意义。
| code / 提示关键词 | 人话意思 | 先查哪里 | 要不要重试 |
|---|---|---|---|
| insufficient_quota | 余额或套餐额度用完 | 查账单与用量记录 | 充值或换渠道后再谈 |
| rate limit / too many requests | 短时间请求太密被拦 | 看自己的并发与重试频率 | 可以，指数退避 |
| context_length_exceeded | 输入超过上下文窗口 | 算 token，砍历史或改分段 | 减完内容再重试 |
| timeout / upstream / server_error | 上游抖动或链路超时 | 记下时间点，看是否集中出现 | 可重试，但设次数上限 |
- 指数退避
- 每次重试间隔翻倍，给上游恢复时间，避免把限流刷成封禁
- 上下文窗口
- 单次请求能容纳的输入上限，超了就要砍或拆
- 用量记录
- 账单页里的调用与消耗明细，是判断额度问题的第一现场
排查顺序：从不用重试的开始排，10 步内定位
把上面两张表合起来用，就得到一条固定排查路径：先排掉不可能靠重试解决的，再处理需要改条件的，最后才进入重试流程。这样你能在几步之内把范围缩小到具体一层。
- 第一步：先读 code判断它属于「配置错」「额度错」「模型名错」「限流」「上游抖动」哪一类，后面的动作全由这个分类决定。
- 第二步：配置类就地改Key、权限、账户状态这三样不改完不要重发请求，改完单次验证即可。
- 第三步：额度类先看账单去账单与用量页确认是欠费、套餐没生效还是被限速，别用调接口的方式试探余额。
- 第四步：模型名类对照列表以 /models 返回的准确名称为准；中转站还要核对它的渠道分组说明，同名模型未必都在转发。
- 第五步：限流与上游类才重试用指数退避、限定次数、记录每次失败的时间与请求参数。
- 第六步：仍复现就交完整材料带完整响应体、时间点、请求参数、复现步骤去问客服，比一句「报错了」有效得多。
先分清楚哪一类错，再决定动不动手重试；顺序对了，排查就是几步的事。
这套速查表什么时候不管用
任何速查表都有边界。下面几种情况，别硬套本文的关键词去对号入座，换个思路更快。判断标准很简单：你手里到底有没有一个可读的 error code。没有，这套表就不适用。
- 错误文本被中转站改写或吞掉时，code 字段可能是空的，只能靠状态码和返回结构倒推
- 自定义兼容层如果自己造了一套错误格式，站内通用速查未必对得上，要看服务方自己文档
- 流式返回中途断流，往往没有完整 error 对象，属于连接层问题，不在本文覆盖范围
- 同一账号多个 Key 混用时，先确认报错请求用的是哪一个，否则排查方向会偏
下一步：把状态码那篇对照看完
这篇解决的是「看得懂英文 code」，状态码那篇解决的是「看得懂响应码与责任划分」。两边对照着看，基本能覆盖日常遇到的绝大多数报错。需要横向对比不同渠道的稳定性与价格，再去站内对应页面核对当时的数字。
常见问题
invalid_api_key 一定是 Key 错了吗？
多数情况下是复制带了空格、换行，或者把某个平台的 Key 用到了另一套协议的地址上。少数情况是 Key 被禁用、过期或站点侧配置变动。先重新复制一次、确认前缀与地址匹配，再考虑是不是账户状态问题。
insufficient_quota 和 rate limit 怎么区分？
前者是「没钱了」，重试再多次也一样；后者是「太快了」，等一会儿大概率就能过。判断方法很简单：看恢复时间，额度类要充值或换渠道才好，限流类退避几秒到几十秒通常自己就好了。
同一个报错在中转站和官方表现不一样，信谁？
以完整响应体为准。中转站的提示语可能被改写，官方文案也可能随版本调整。碰到不一致，把请求参数、时间点、完整返回都记下来，再到 /sites 看看这家站点有没有别的反馈，别只凭一句话下结论。
