API 调用报错排查：401 / 404 / 429 / 524 常见错误对照表

调用模型 API 遇到报错，90% 的情况落在下面这几种。按状态码对号入座。

401 Unauthorized：认证失败

含义：服务器认为你的 Key 无效。

问题位置：你的配置。

排查动作：

1. Key 是否复制完整（sk- 开头，无多余空格换行）
2. Key 是否已过期或被删除
3. 认证头格式：Authorization: Bearer sk-xxx（注意 Bearer 后有一个空格）
4. 少数端点用 x-api-key 头而不是 Bearer——看服务商文档

403 Forbidden：无权限

含义：Key 有效，但没权限做这件事。

常见原因：

• 账户余额不足，被服务方限制
• 该 Key 被限制只能调用部分模型
• IP 白名单类限制
• 地区限制（部分官方 API 有此问题）

排查动作：查控制台余额和 Key 的权限设置。

404 Not Found：路径错误

含义：请求的地址不存在。

问题位置：Base URL 配置。

排查动作：

1. /v1 多了还是少了——对照服务商文档，这是 404 的第一大原因
2. 路径拼写：/v1/chat/completions 是标准路径
3. Claude 系协议是 /v1/messages，不是 chat/completions
4. 用 curl 直接测试端点，把工具层的变量先排除

429 Too Many Requests：限速

含义：请求太频繁，或账户等级的速率上限到了。

排查动作：

1. 降低并发（并行跑任务时最容易撞）
2. 加重试逻辑：收到 429 后退避几秒再试（指数退避）
3. 查服务商的速率限制文档，不同模型限制不同
4. 长期撞限制说明该升级账户等级或换服务商了

500 / 502 / 503：服务端故障

含义：问题在服务商那一侧。

排查动作：

1. 先重试一次（很多是瞬时抖动）
2. 查服务商的状态页或群公告
3. 持续 503 时切备用模型或备用端点——这就是为什么建议配置两个服务商

524：网关超时（Cloudflare 特有）

含义：源站在 100 秒内没返回结果，Cloudflare 掐断了连接。

常见场景：

• 超长上下文推理，模型响应太慢
• 端点背后没有做流式传输，长任务必然超时

排查动作：确认客户端开启了流式（stream: true）；长任务拆分；联系服务商确认其网关的超时配置。

400 Bad Request：请求格式错误

含义：请求体里有服务方不接受的东西。

常见原因：

• model 字段名错误或缺失
• max_tokens 超过模型上限
• 消息格式不对（比如 messages 数组结构错误）
• 多模态内容格式不符合该端点的要求

排查动作：看返回的 error message——正规的错误信息会明确说哪个字段有问题。

万能排查三步法

任何报错，按这个顺序定位：

1. curl 复现：绕开所有工具，直接用命令行打端点。通了 → 问题在你的工具配置；不通 → 问题在网络或服务方
2. 读错误信息：error body 通常已经告诉你原因了，别只看状态码
3. 分层排除：网络（ping/curl）→ 认证（Key）→ 路径（Base URL）→ 参数（模型名、请求体）

---

更多排查案例随实际遇到持续更新到本文。相关：第一次配置 API 的完整流程