Source: https://wiki.niceai.dev/guide/tech/troubleshooting-checklist

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

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

## 第一步：拿到完整的错误信息

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

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

状态码基本决定了排查方向，可以对照 [常见错误码对照](https://wiki.niceai.dev/guide/error-codes)。

## 第二步：用 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 持续几分钟以上，或者扣费和使用记录对不上时，带上**发生时间、模型名、状态码和错误信息**（不要带密钥）联系服务方，排查会快很多。

## 延伸阅读

- [常见错误码对照](https://wiki.niceai.dev/guide/error-codes)
- [同一个 API，为什么各个工具的 Base URL 写法都不一样](https://wiki.niceai.dev/guide/tech/base-url-rules)
- [限流、超时与重试](https://wiki.niceai.dev/guide/api/rate-limits)
