你正在调试一个调用大模型 API 的应用，代码跑了几分钟，突然抛出报错：状态码 429、500，或者干脆没返回，请求挂死；更头疼的是返回了 200，但 AI 回答空白。这个问题几乎每个开发者都会遇到。本文换个角度——按你实际看到的报错症状来排查，从 HTTP 4xx、5xx 到无内容的 200，一步步带你走通。

拿到报错后第一步做什么？

别急着改代码，先完成三件事，后续排查效率翻倍。

1. 保存完整的报错痕迹

你需要：HTTP 状态码、响应 Body 中的 error 或 message 字段、请求头（至少记下 Authorization 和 Content-Type）、请求 URL（含 API 版本号）、耗时。如果请求无返回，记下超时时间、代理配置和网络环境。

2. 快速判断能否直接重试

  • 429 或 5xx：可重试 1-2 次，但要有间隔，避免无冷却重复请求。

  • 4xx（400、401、403、404）：立即停止重试，问题出在请求本身，需修改代码。

  • 无状态码（超时、断开）：可尝试一次更短超时的重试，两次失败则转向网络排查。

3. 30 秒快速检查清单

  1. API Key 是否刚过期？去后台看有效期。

  2. 是否换了模型名却没更新代码（如 gpt-3.5-turbo 改 gpt-4 没改 model 字段）？

  3. 公司网络是否换了代理？

  4. 账户额度是否用光？前三项常是“昨天能用，今天报错”的元凶。

日志是最好的武器

建议在每次 API 调用前后记录 JSON 格式日志，包含时间戳、request_id、model、endpoint、http_status、error_code、latency_ms 等。Python 中可用 logging 库实现。积累数千条后，可写脚本按状态码分组聚合，发现高频错误（如 429 超过 5% 则提示“降低频率”），避免在无关错误上浪费时间。

第一类：HTTP 4xx —— 客户端错误

400 参数错误

最常见且难定位。排查路径：① 检查 JSON 格式是否合法（如多逗号、缺引号）；② 检查必填字段，messages 必须是数组且至少一条；③ 模型名拼写正确（从官网复制）；④ 参数值在范围内（如 temperature 0-2，max_tokens>0）。

401/403 认证与权限

  • 401：API Key 无效或未传入。检查 Key 拼写、有效期、是否在请求头中（Authorization: Bearer YOUR_API_KEY）。

  • 403：Key 有效但无权限。常见原因：账户未购买该模型额度、IP 不在白名单、地域限制。去后台添加公网 IP 或更换网络出口。

各厂商差异：上下文超限 OpenAI 返回 400（context_length_exceeded），百度文心提示“输入长度超过最大限制”。模型不可用 OpenAI 返回 404，有些厂商返回 403。建议自建对照表，查常见错误码的中文描述与解决方式。

第二类：HTTP 429 —— 被限流

这是唯一“多等一会儿就能恢复”的错误。捕获后优先读取响应头 Retry-After，若无则用指数退避（1s、2s、4s……），并设最大重试次数。降低被限流的概率：客户端做请求队列控制频率；备用模型切换（注意成本、延迟差异）；关注额度档位，业务量上升时尽快升级。

第三类：HTTP 5xx —— 服务端错误

  • 500：临时问题，重试间隔≥10秒。

  • 502/503：上游不可用或过载，间隔≥30秒。

  • 504：可能网络传输慢或服务器处理不过。 用 curl -v --connect-timeout 10 --max-time 30 快速验证网络连通性。若 curl 也超时，排查 DNS、代理、防火墙。代码中永远设超时，Python requests 推荐 timeout=(5,30)。

第四类：返回 200 但数据为空或奇怪

内容被安全过滤

查看 finish_reason 是否为 content_filter。若是，细化 system message，换表述，或联系服务商调低敏感度。

上下文长度超限

表现为输出截断或只有开头。检查响应中 token 数，若超过模型上限则截断早期对话或压缩内容，并适当降低 max_tokens。

随机性导致奇怪回答

降低 temperature 至 0.1-0.3，固定 seed 参数（部分模型支持）。

附录：厂商错误码参考（示例）

错误类型OpenAI百度文心通义千问上下文超限context_length_exceeded输入长度超过最大限制max context length exceeded模型不可用Model not found模型不存在或未授权模型不存在或已下线内容过滤content_filter内容安全审核失败内容被安全策略拦截Key无效invalid_api_keyAPI Key无效auth failed

非技术用户排查清单

  1. API Key 是否失效？去后台查看。

  2. 额度是否用尽？看余额或剩余调用次数。

  3. 是否在允许范围？检查 IP 白名单。

  4. 是否是维护时间？查服务商公告。

  5. 以上都不符合，截图完整报错信息给技术支持。

遇到报错时，记住原则：先找状态码和关键词，按“客户端→限流→服务器→内容”顺序排查。没有万能解，但一套可重复的 SOP 能解决 90% 的问题。建议整理成团队检查清单，下次报错先从看日志开始，而不是改代码。