API 报错怎么查:先看状态码,再看错误体
报错信息通常比你以为的更完整,答案就在返回体里。本文把状态码分成四类(请求写错、身份不对、现在不行、服务端问题),指出错误体里真正有用的三个字段 —— 尤其是最容易被忽略的请求标识,并给一个五步排查顺序和最常撞到的五个报错对照。

一次报错长什么样
报错信息本身通常比你以为的更完整。 很多人在这里就放弃了,翻文档找相似报错,其实答案就在返回体里。
一次 API 调用的失败,通常长这样:HTTP 状态码,加上一段结构化的错误体。
以 DeepSeek 官方文档的「错误码」页为例,它把错误分成几类并给出对应的建议动作。认证类要检查 key 格式与账户状态;余额与限流类说明该等多久或该调什么参数;请求本身的问题说明哪一项不合法。
OpenAI 的文档则把「Structured Outputs」列为让输出符合 schema 的手段。也就是说,连「返回的格式不对」这件事,在接口层面都有对应的处理方式,不是只能靠改提示词。
所以排查的顺序是固定的:先分类,再看体,最后才动手改。
按状态码分成四类
| 类别 | 常见状态码 | 先查什么 |
|---|---|---|
| 请求没到服务端 | 400、422 | 必填字段、类型、格式、长度限制 |
| 身份或权限不对 | 401、403 | key 是否有效、账户状态、是否需要额外开通 |
| 服务端接了但没给办 | 429 | 限流还是余额;看响应头里的重试信息 |
| 服务端自己出了问题 | 500、502、503 | 重试、换区域、稍后再看 |
400 和 422 属于「你写错了」,改请求就行,重试没有意义。
401 和 403 属于「你不是你以为的你」,检查 key、账户、权限范围。
429 属于「现在不行」,先分清是并发超了还是额度用完了。前者退避重试,后者得充值或者改用量。
5xx 属于「不是你的问题」,可以重试,但连续几次之后要怀疑是服务端的问题而不是你。
有个容易搞混的点:429 有时不是限流而是余额不足。两者状态码一样,但处理完全相反——一个等,一个充。所以看错误体,不能只看码。

