Skip to content

大模型 API 调用失败怎么排查 ​

按这个顺序查,大部分问题几分钟内就能定位:先看 HTTP 状态码和错误信息 → 用 curl 绕开客户端直接请求 → 依次核对地址、密钥、模型名、参数 → 最后才考虑网络和限流。核心思路是把“服务的问题”和“客户端配置的问题”分开。

第一步:拿到完整的错误信息 ​

截图里只有“请求失败”几个字是没法排查的。至少要拿到:

  • HTTP 状态码(401、404、429……)
  • 错误体里的 message 字段
  • 实际请求的 URL(很多客户端在日志或开发者工具里能看到)

状态码基本决定了排查方向,可以对照 常见错误码对照。

第二步:用 curl 绕开客户端 ​

bash
curl -i https://api.example.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "<模型名>", "messages": [{"role": "user", "content": "hi"}]}'
  • curl 成功、客户端失败:问题在客户端配置,重点查 Base URL 拼接和客户端的协议选择。
  • curl 也失败:问题在密钥、模型名、账户状态或服务本身,按状态码继续查。

Windows PowerShell 里 curl 可能是 Invoke-WebRequest 的别名,请用 curl.exe。

第三步:按顺序核对 ​

顺序检查项典型症状
1Base URL:是否多了或少了 /v1404,或 /v1/v1/
2协议:OpenAI 兼容、Anthropic、Gemini 是否选对404、400、返回格式解析失败
3密钥:是否完整、有无空格换行、是否被禁用401
4账户与权限:余额、密钥分组能否用该模型403
5模型名:大小写、版本后缀是否与列表一致404 或 400,提示模型不存在
6参数:该模型是否支持你传的参数400
7上下文长度:输入加输出是否超限400,提示 context length
8频率:并发是否过高429
9网络:代理、防火墙、DNS超时、连接被重置

几个常见误区 ​

  • 改了环境变量不重开终端:环境变量只对之后新开的终端生效,编辑器内置终端要重启编辑器。
  • 两个地方都配了:配置文件和环境变量同时存在、值又不同,实际用的可能不是你以为的那个。
  • 把 400 当成服务故障反复重试:400 是请求本身的问题,重试一万次结果也一样。
  • 贴日志时带上了密钥:求助前先搜一下 sk-,把密钥打码。

什么时候该找客服 ​

curl 也复现、并且状态码是 5xx 持续几分钟以上,或者扣费和使用记录对不上时,带上发生时间、模型名、状态码和错误信息(不要带密钥)联系服务方,排查会快很多。

延伸阅读 ​

NiceAI · 稳定的 AI 大模型 API 中转站