外观
大模型 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。
第三步:按顺序核对
| 顺序 | 检查项 | 典型症状 |
|---|---|---|
| 1 | Base URL:是否多了或少了 /v1 | 404,或 /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 持续几分钟以上,或者扣费和使用记录对不上时,带上发生时间、模型名、状态码和错误信息(不要带密钥)联系服务方,排查会快很多。