大模型 API 报错速查：401、403、500、超时排查方法
一张表定位常见 API 报错：401 是 Key 问题、403 是权限问题、500 在服务端、超时多半是上下文过长。附最小验证脚本和排查顺序，五分钟定位问题出在哪一层。
接入大模型 API 时，报错信息往往只有一行英文加一个状态码。同一句 error，可能出在你的代码、Key、网络，也可能出在服务端——乱试一通不如按状态码定位。这篇把 429 以外的高频报错整理成一张速查表，配上排查顺序和最小验证脚本，出问题时照着走一遍，多数五分钟内能定位。
速查表：状态码 → 原因 → 处理
| 状态码 | 典型报错信息 | 真实原因 | 处理方式 |
|---|---|---|---|
| 400 | invalid_request_error | 参数格式错、必填字段缺失 | 按报错里指出的字段检查请求体 |
| 400 | context length exceeded | 输入+输出超过模型上下文上限 | 裁剪历史或换长上下文模型 |
| 401 | invalid_api_key | Key 错误、被作废、或格式不对 | 换 Key 重试，见下文 |
| 403 | permission denied | 无该模型权限、账号受限 | 检查模型分组权限 |
| 404 | model not found | 模型名拼写错误或不可用 | 核对可用模型列表 |
| 429 | rate limit exceeded | 触发限流 | 见 429 专题文章 |
| 500 | internal server error | 服务端异常 | 重试，持续出现再反馈 |
| 502/503 | bad gateway / service unavailable | 上游不可用或网关维护 | 等待或切换模型 |
| 无响应 | 超时 | 网络不通或响应太慢 | 见超时排查 |
429 已单独写过一篇：大模型 API 429 报错：原因、重试与并发调优，这里不重复。
401：先排除 Key 自身的三个坑
401 是最常见也最容易误判的。按顺序检查：
- Key 是否完整。复制粘贴时截断（少了开头
sk-或结尾几个字符）、中间混入空格或换行符，都表现为 401。用len(key)和key[:5]打印确认。 - Key 是否还有效。确认没有过期或被作废；如果你轮换过 Key，旧 Key 全局搜索一遍，确认没有残留引用。
- 认证头格式。必须是
Authorization: Bearer sk-xxx，注意 Bearer 后有一个空格。SDK 里传api_key参数一般不会错，手写 curl 最容易错。
403 和 404：权限与模型名
403 和 401 的区别在于：401 是「我不认识你」，403 是「认识你，但你没权限」。多数聚合网关按分组或套餐区分可用模型，你的分组没有开通某个模型的权限时就报 403。检查自己在用的分组，或换一个该分组可用的模型。
404 报 model not found 时，先核对模型名拼写。一个常见坑是大小写和点号：gpt-4o-mini 和 gpt4o-mini、claude-sonnet-4-5 和 claude-4-sonnet 这类变体，不同平台命名规则不同，以平台的模型列表页为准。
500 与超时：区分「它坏了」和「你太慢」
5xx 是服务端问题，重试即可。但要注意持续性：偶发一次不用管；同一模型连续 500 超过几分钟，说明该模型或该通道当前不可用，切换备用模型比等待高效。
超时的排查重点是分清发生在哪一段：
- 连接超时（TCP 连不上）：网络问题，检查代理、防火墙、DNS
- 首字节超时（连上了但迟迟不返回）：模型排队或推理慢，长上下文请求尤其明显
- 读取中途超时（流式输出断在半路）：SSE 连接被中间层切断，处理方式见 流式输出 SSE 原理与调试
上下文过长的请求是最常见的超时来源：几万 token 的输入，推理时间本身就长，再叠加默认 60 秒的客户端超时就报错了。解法是显式调大超时参数、开启流式输出（首字节快，能避开读超时）或裁剪输入。
最小验证脚本
报错时先跑这段，把「网络、认证、模型」三层一次性验完：
curl -sS -w "\nHTTP_CODE:%{http_code}\n" https://api.zaimod.com/v1/chat/completions \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"hi"}],"max_tokens":10}'结果判断：
- 返回正常 JSON + 200：网络、Key、模型都没问题，问题在你的业务代码参数上
- 401：Key 问题，按上文三步排查
- 403/404：权限或模型名问题
- 连接失败：网络问题
- 200 但业务代码仍报错：检查 SDK 版本、参数透传、base_url 拼写
这段 curl 能通过而你的代码不行时，优先怀疑 base_url 或协议兼容性，参考 base_url 迁移后失效的 5 个功能实测。
常见问题
Q：报错信息里说 invalid_api_key，但 Key 明明是对的？
检查是不是向网关传了官方渠道的 Key（或反过来）。两者的 Key 不通用，确认你的 base_url 和 Key 配套。
Q：同一个模型有时 200 有时 500，正常吗？
偶发 5xx 属正常波动，重试即可。若同一模型 5xx 比例持续超过 2%，说明通道不稳，换模型或联系服务方。
Q：400 报 context length exceeded，但我输入没有很长？
上下文上限是输入加输出之和。max_tokens 设得太大也会挤占空间；另外多轮对话的历史会累积，别忘了算上系统提示和历史轮次。
延伸阅读
- OpenAI API 中转站怎么选：2026 版避坑清单
- OpenAI 兼容协议是什么：原理、边界与用法
- 大模型 API 429 报错：原因、重试与并发调优
- 接入前先注册一个聚合网关 Key，配合本文的验证脚本五分钟跑通第一个请求