先看状态码，别急着复制报错去搜
前几天帮朋友接大模型 API，他发来一屏幕报错截图，问我是不是网络被墙了。我瞄了一眼状态码：429。再看内层信息：「您的账户已欠费，请充值后重试」。跟网络半毛钱关系没有，充值就解决了。
这种事我遇到过太多次。报错信息其实写得挺清楚，但很多人的习惯是只盯着 message 里的英文单词瞎搜，或者看到一片红就慌。这篇把我排查 AI API 报错的顺序整理出来。DeepSeek、Kimi、智谱、OpenRouter 四家的官方错误码文档我最近都翻过一遍，各家有各家的怪脾气，挑重点说。
先说分诊思路。AI API 的报错一般分两层：外层是 HTTP 状态码，内层是 JSON 里的错误描述。状态码是分诊台，三秒钟把问题分进四个筐：
- 401 / 403：你的问题，key 或权限
- 400 / 422：你的问题，请求参数
- 402 / 429：九成是钱的问题
- 500 / 503：服务商的问题，等就行
分完筐，再靠内层信息定位细节。
401：key 错了，但不一定是 key 本身的错
401 是认证失败，我实际碰到的三种情况，按出现频率排：
第一，复制 key 时带了空格或换行。我中过招，终端里粘贴看着挺正常，实际末尾藏了个换行符，服务端校验直接挂。用 echo -n "$API_KEY" | wc -c 数一下长度就能确认。
第二，base_url 和 key 不匹配。用中转站的朋友容易犯：key 是官方的，URL 却填了中转站的，或者反过来。两边的 key 体系完全不通，谁也认不了谁。
第三，Kimi 的中西站隔离。这个坑是我翻 Kimi 官方错误码文档才注意到的：platform.kimi.com（中国站）和 platform.kimi.ai（国际站）的账户、余额、API Key 完全独立，混用直接返回 401。文档原话是「请确认调用端点与 Key 所属平台一致」。检查下你 key 的域名前缀和调用的域名是不是一家。
智谱还有一个 1003：Authentication Token 已过期，去后台重新生成一个就好。
402，和伪装成 429 的欠费
DeepSeek 把欠费单列为 402（Insufficient Balance），错误码表里写得明明白白，看到就去充值，没什么好说的。
有意思的是智谱。它的欠费业务码是 1113，但外层 HTTP 状态码挂在 429 下面。你要是只看状态码，会以为是请求发太快，然后拼命给脚本加延迟。没用，欠费就是欠费，加到一分钟一次也一样报错。这就是为什么我一直强调内层业务码必须看。
智谱家挂在 429 底下的还有几种：1302 是速率限制，1305 是模型访问量过大，1308 是用量到达上限。同一个 429，处理动作完全不同。
429：先读内层码，再决定动不动代码
429 字面意思是「请求太多」，实际可能是三种事里的一种：
- 真的发太快：加延迟，重试加退避（retry + backoff）
- 钱的问题：智谱 1113、OpenRouter 余额不足（它家是 402）
- 服务端忙：智谱 1305 这种，等一会重试就行，代码一行不用改
Kimi 文档里 429 直接叫「速率限制 / 额度不足」，一个状态码两种含义，同样要靠内层 message 分流。看到 429 就无脑降频，是我见过最浪费时间的处理方式。
400 / 422：九成是上下文超长
参数类报错里我见得最多的是上下文超限。典型现象：平常单聊没问题，一传大文件就报 400。Kimi 文档对应的 message 是 "Input token length too long"，处理就两条路，缩短输入，或者换更大上下文窗口的模型。
还有一种是 prompt tokens 加上 max_tokens 超过模型规格，把 max_tokens 调小就好。这类问题单聊时不容易暴露，一接长文档就炸。
智谱把参数错误拆得很细：1261 是 Prompt 超长，1211 是模型不存在（十有八九是 model 参数手打错了），1301 是内容安全拦截。看到 1301 别反复重试，改提示词，越重试越报错。
DeepSeek 那边 400 和 422 都有：400 是请求体格式错误，422 是参数非法。共同点是根据 message 里的提示改请求，别凭感觉。
5xx，和一个隐藏坑：HTTP 200 里藏着错误
500 / 503 是服务端的问题。DeepSeek 文档的建议就是稍等重试，503 是过载，高峰期常见，真没什么可操作的。
但有个坑值得单独拎出来：流式调用。OpenRouter 文档明确写了，只要模型开始吐字，HTTP 状态码就是 200，中途发生的错误会混在响应体或 SSE 事件里。也就是说你不能判断完 HTTP 200 就当成功，流式解析时要检查数据里有没有 error 字段。
我之前写过一个采集脚本没做这个检查，某次模型中途挂了，脚本把半截回答当正常结果存进了数据库，第二天才发现。从那以后我所有流式解析都先过一遍 error 字段。
我的排查顺序，五步
- 看外层状态码：4 开头是我的事，5 开头是服务商的事
- 401 先查 key 里的空格和 base_url 是否匹配，Kimi 用户再查中西站
- 429 别急着降频，先看内层码是不是欠费（智谱 1113 就是典型）
- 400 / 422 先怀疑上下文超长，再查 model 拼写和参数
- 5xx 和流式中断：加重试逻辑，等一会再跑
报错本身不可怕，可怕的是不看状态码就开搜。这套顺序用熟了，大部分问题两分钟内能定位到该充值、该改代码还是该等着。
计费怎么算、哪些开关能省钱，我在上一篇 API 计费里写过；Kimi 和智谱的上手教程站里也有。报错排查配上那几篇，接 API 这条路基本就顺了。