在配置 Claude Code、AI SDK、后端服务或自定义 Anthropic API 网关时，最常见的问题不是“模型坏了”，而是 API Key、Base URL、Endpoint、模型名、请求体、网络代理或账号权限没有配置对。

很多开发者遇到 AI API 调用失败时，只看到一行“调用失败”或 APIConnectionError，然后就开始改代码。实际排查时，更有效的方法是先拿到完整错误信息，再判断问题属于哪一类：

• 鉴权问题：API Key 错误、Header 格式不对、环境变量没生效；
• 路由问题：Base URL、Endpoint、接口版本写错；
• 模型问题：模型名不存在、模型下线、账号没有权限；
• 请求问题：JSON 结构、参数范围、工具调用 schema 不符合要求；
• 限制问题：上下文太长、文件太大、触发 RPM/TPM 或余额不足；
• 网络问题：代理、DNS、TLS、防火墙、Docker 环境异常；
• 平台问题：服务商过载、网关异常、区域节点故障。

本文按开发者实际配置流程来整理：先确认环境变量和最小请求，再根据 HTTP 状态码定位具体原因，最后给出线上稳定性建议。

---

一、先确认 4 个关键信息

在排查 Claude Code、Anthropic API 网关或其他 AI API 调用失败前，建议先收集下面 4 类信息。

1. HTTP 状态码

常见状态码包括：

• 400：请求参数错误；
• 401：鉴权失败；
• 403：没有访问权限；
• 404：Base URL、Endpoint 或模型名错误；
• 408 / 504：请求超时；
• 413：请求体过大；
• 422：参数结构校验失败；
• 429：触发限流或额度不足；
• 500 / 502 / 503：服务端或上游网关异常。

不同状态码对应的排查方向完全不同，不建议只看“调用失败”这类笼统提示。

2. 完整错误响应体

重点关注这些字段：

error.code
error.message
type
request_id

如果使用的是 SDK，也要尽量打印原始 response body，而不是只打印 SDK 包装后的异常信息。

3. 当前运行环境

同一段代码在不同环境里可能表现完全不同：

• 本地可以，服务器不行；
• Postman 可以，代码不行；
• Docker 容器里失败；
• CI/CD 环境里失败；
• 非流式正常，stream 流式输出失败。

这些差异通常能直接缩小排查范围。

4. 最近是否改过配置

如果最近改过下面内容，需要优先排查：

• API Key；
• Base URL；
• Endpoint；
• 模型名；
• SDK 版本；
• 代理配置；
• 中转网关；
• 账单或额度配置；
• 服务商控制台里的项目、组织或权限设置。

很多 API 调用失败并不是代码突然坏了，而是账号权限、模型状态或平台策略发生了变化。

---

二、推荐的 5 分钟快速定位流程

排查 AI API 调用失败，可以按下面顺序来做。

第一步：打印完整错误信息

不要只输出：

调用失败

建议至少记录：

provider
base_url
endpoint
model
http_status
error_code
error_message
request_id
latency_ms
retry_count
trace_id
stream

如果线上系统没有这些字段，后续排查会非常被动。

---

第二步：用 curl 发最小请求

先绕开业务代码、SDK 封装、复杂参数和工具调用，只发送一个最小请求。

curl -X POST "https://api.example.com/v1/chat/completions" \
  -H "Authorization: Bearer $AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model-name",
    "messages": [
      {"role": "user", "content": "hello"}
    ],
    "max_tokens": 50
  }'

如果这个最小请求能成功，说明 API Key、Base URL、模型名和基础网络链路大概率是通的，问题更可能在：

• 业务代码；
• SDK 配置；
• 请求体结构；
• 环境变量读取；
• 代理配置；
• stream 读取方式；
• 工具调用或多模态参数。

如果 curl 也失败，就优先检查：

• API Key；
• Header；
• Base URL；
• Endpoint；
• 模型名；
• 账号权限；
• 网络链路；
• 服务商状态。

---

第三步：检查环境变量是否生效

很多线上问题都出在环境变量。

常见配置项一般包括：

AI_API_KEY=your_api_key
AI_BASE_URL=https://api.example.com/v1
AI_MODEL=your-model-name
HTTPS_PROXY=http://127.0.0.1:7890

需要确认：

• 本地和服务器是否使用同一个 Key；
• Docker 容器是否拿到了环境变量；
• CI/CD 是否注入了正确变量；
• .env 是否被实际加载；
• 代码读取的变量名是否和配置文件一致；
• 服务重启后新环境变量是否生效；
• 是否读到了空值、旧值或测试环境的 Key。

可以临时在安全环境中打印变量是否存在，但不要把完整 API Key 打到日志里。

---

第四步：确认 Base URL、Endpoint 和接口版本

AI API 经常存在多种接口格式，例如：

• /v1/chat/completions
• /v1/responses
• generateContent
• 自定义兼容网关路径

常见错误包括：

• /v1 多写或少写；
• Base URL 和 endpoint 重复拼接；
• 官方接口地址和自定义网关地址混用；
• SDK 默认 base_url 覆盖了你的配置；
• 网关转发时路径拼错；
• 把不同平台的请求结构混在一起使用。

要特别注意：“兼容 OpenAI 格式”不代表所有能力都 100% 一致。文件上传、工具调用、JSON mode、stream、多模态输入等功能，可能因为实现不同而存在差异。

---

第五步：确认模型名和账号权限

如果换模型后突然失败，优先排查模型名和权限，而不是先改代码。

常见原因：

• 模型名拼写错误；
• 模型已经下线、迁移或改名；
• 当前账号没有开通该模型；
• 免费账户、试用账户或特定项目不能使用部分模型；
• 模型在当前区域不可用；
• 自定义网关没有映射该模型；
• 模型不支持图片、工具调用、JSON 输出或流式响应。

不要直接把网上示例里的模型名复制到生产环境使用。更稳妥的做法是以控制台、模型列表或平台文档中当前账号实际可用的模型为准。

---

三、常见 HTTP 状态码与排查方向

状态码 / 错误类型	常见含义	AI API 常见原因	优先排查
400 Bad Request	请求参数错误	JSON 写错、字段名不对、缺少 model、参数范围不合法	请求体
401 Unauthorized	鉴权失败	API Key 错误、Key 过期、Header 格式不对	API Key
403 Forbidden	没有权限	模型没权限、区域限制、项目不匹配、Key 被禁用	账号权限
404 Not Found	资源不存在	Base URL 错、Endpoint 错、模型名不存在	URL / 模型名
408 / 504 Timeout	请求超时	模型响应慢、上下文太长、网络慢、网关超时	超时和输入长度
413 Payload Too Large	请求过大	文本、图片、文件或上下文超过限制	请求大小
422 Unprocessable Entity	参数校验失败	schema 不符合要求、工具参数错误、多模态结构不对	参数结构
429 Too Many Requests	限流或配额耗尽	RPM/TPM 超限、余额不足、免费额度用完	配额和限流
500 Internal Error	服务端异常	服务商故障、模型内部错误、输入触发异常	状态页 / 重试
502 / 503 Unavailable	服务不可用	上游过载、代理异常、模型容量不足	重试 / 切模型
APIConnectionError	连接失败	DNS、代理、防火墙、TLS、网络阻断	网络链路
Content Policy Error	内容被拒绝	输入内容或提示词触发安全策略	输入内容

错误码只是入口。更可靠的判断方式是把：

错误码 + 错误信息 + 请求体 + 运行环境 + 账号状态

放在一起看。

---

四、401：API Key 错误或鉴权格式不对

401 Unauthorized 是最典型的鉴权类错误。

常见提示包括：

Invalid API key
No API key provided
AuthenticationError

常见原因：

• API Key 复制错了；
• 前后多了空格或换行；
• Header 里少写了 Bearer；
• 环境变量没有生效；
• 代码读到的是空值或旧值；
• 本地和服务器不是同一个 Key；
• Key 被撤销、过期或禁用；
• 多组织、多项目、多工作区下，Key 和项目没有对应；
• 官方 Key 和第三方兼容平台 Key 混用。

请求头通常应类似这样：

Authorization: Bearer your_api_key
Content-Type: application/json

排查建议：

1. 确认 Key 没有多余空格和换行；
2. 确认 Header 中包含 Bearer；
3. 确认运行环境读取到的是正确变量；
4. 确认当前 Key 对应正确项目、组织或工作区；
5. 如果使用自定义网关，确认 Key 和 Base URL 来自同一个平台。

---

五、404：Base URL、Endpoint 或模型名错误

404 Not Found 不一定是接口不存在，也可能是路径、接口版本或模型名错误。

常见问题：

• Base URL 写错；
• endpoint 写错；
• /v1 多写或少写；
• SDK 自动拼接路径导致重复；
• 模型名不存在；
• 自定义网关没有映射该模型；
• 把不同平台的接口格式混用。

例如下面几类接口就不能直接当成同一种格式使用：

/v1/chat/completions
/v1/responses
generateContent

如果你配置的是自定义 Anthropic API 网关，建议重点确认：

• SDK 是否支持自定义 base_url；
• Base URL 是否包含 /v1；
• endpoint 是否被 SDK 自动追加；
• 模型名是否为网关实际支持的名称；
• 网关是否兼容当前请求参数。

---

六、400 / 422：请求体格式不符合接口要求

400 和 422 通常说明请求结构或参数不符合要求。

常见原因：

• JSON 语法错误；
• 少逗号、多逗号、引号不匹配；
• Content-Type 不是 application/json；
• messages、input、contents 混用；
• role 写错；
• 消息数组结构不符合要求；
• temperature、top_p、max_tokens 超出允许范围；
• 工具调用 schema 不符合 JSON Schema；
• 多模态输入中的图片、文本、文件结构不符合平台规范。

推荐排查方式：

1. 先用官方最小示例验证；
2. 再加入系统提示词；
3. 再加入历史消息；
4. 再加入工具调用；
5. 最后加入多模态内容或复杂参数。

只要最小请求能跑通，再逐步加回参数，通常很快能定位到是哪一段请求体出问题。

---

七、上下文、Token、文件或图片超过限制

AI API 和普通 HTTP API 不同，除了请求体大小，还要关注：

• 上下文窗口；
• 输入 token；
• 输出 token；
• 文件大小；
• 图片数量；
• 图片分辨率；
• 图片格式；
• 网关超时时间。

常见场景：

• 历史对话一直追加，prompt 越来越长；
• RAG 检索结果拼接过多；
• max_tokens 设置过大；
• 上传文件超过平台限制；
• 图片数量或格式不符合要求；
• 输入太长导致 400、413、超时，甚至触发 500 类错误。

处理方式：

• 裁剪历史消息；
• 对长文本先做摘要压缩；
• 限制 RAG 的 top_k；
• 控制最大输出长度；
• 文件分块处理；
• 请求前估算 token 使用量；
• 大请求单独设置更合理的超时时间。

---

八、429：限流、并发过高或额度用完

429 Too Many Requests 不只是“请求太快”，也可能和额度、余额、账单状态有关。

常见限制包括：

• RPM：每分钟请求数；
• TPM：每分钟 token 数；
• RPD：每天请求数；
• 并发请求数；
• 项目级额度；
• 组织级额度；
• Key 级额度；
• 免费额度；
• 账单状态；
• 硬限额；
• 自定义网关自身额度或限流。

不建议遇到 429 就无限重试。更合理的做法是：

• 降低并发；
• 使用请求队列；
• 缩短 prompt；
• 减少最大输出 token；
• 使用指数退避；
• 增加随机抖动；
• 申请提额；
• 绑定账单；
• 设置余额和用量告警。

重试策略可以只针对这些错误：

408
429
500
502
503
504
网络超时

对于 400、401、403、404，盲目重试通常没有意义，应先修参数、权限或配置。

---

九、网络、代理、DNS、防火墙和 TLS 问题

如果出现：

APIConnectionError
connection timeout
TLS error
connection refused

需要重点检查网络链路。

常见原因：

• 本地能访问，但服务器不能访问外网；
• 云服务器安全组限制出站流量；
• 防火墙拦截；
• Docker 容器没有正确配置代理；
• 公司网络拦截 HTTPS；
• 代理不支持 HTTPS；
• DNS 解析失败；
• 不同环境 DNS 解析结果不同；
• TLS 证书库过旧；
• 系统时间不准确；
• 海外或跨区域链路不稳定。

可以在服务器上执行：

curl -v https://api.example.com
nslookup api.example.com
echo $HTTPS_PROXY

不要只在本地测试。很多“本地成功、服务器失败”的问题，本质是服务器环境缺少代理、证书、环境变量，或者出站规则被限制。

---

十、stream 流式响应中断或没有输出

如果非流式请求正常，但 stream 流式输出失败，通常不是模型本身的问题，而是链路中某一层不支持长连接或 SSE。

常见原因：

• Nginx 开启响应缓冲；
• API 网关开启 buffering；
• Cloudflare 等代理层中断长连接；
• 代理不支持 SSE；
• 代理不支持分块传输；
• 客户端没有逐块读取响应；
• Serverless 函数执行时间太短；
• 网关超时；
• 中转代理的流式分片格式和官方不一致；
• 浏览器端 Header 或 EventSource 使用方式不兼容。

处理建议：

• 关闭代理缓冲；
• 延长网关超时时间；
• 使用支持 SSE 的客户端库；
• 客户端逐块读取响应；
• 长输出拆成多段生成；
• 先切换为非流式请求验证基础链路；
• 确认自定义网关是否明确支持 stream。

---

十一、SDK 版本过旧或接口迁移不兼容

有时官方文档里的示例能跑，但项目里报错，可能是 SDK 版本和文档版本不一致。

常见问题：

• 旧 SDK 不支持新模型；
• 旧 SDK 不支持新接口；
• SDK 主版本升级后调用方式变化；
• 返回字段结构变化，代码读到空值；
• TypeScript 类型定义和实际参数不匹配；
• Python 包版本冲突；
• Chat Completions、Responses API、Assistants/Agents、Gemini SDK 结构混用；
• 自定义网关只兼容部分 OpenAI 风格接口。

建议：

• 固定 SDK 版本；
• 查看 changelog；
• 用原生 HTTP 请求做最小验证；
• 不要在同一个项目里混用不同版本文档中的写法；
• 升级 SDK 前先在测试环境验证请求体和返回字段。

---

十二、500 / 502 / 503 / 504：服务端或上游网关异常

500、502、503、504 不一定是你的代码问题，也可能来自模型服务、上游网关、区域节点或自定义代理层。

常见情况：

• 模型容量不足；
• 服务商局部故障；
• 上游服务过载；
• 高峰期延迟升高；
• 网关转发失败；
• 某个区域或线路临时异常；
• 输入内容触发模型内部异常。

处理方式：

• 做有限重试；
• 使用指数退避和随机抖动；
• 切换模型；
• 切换区域或线路；
• fallback 到备用模型；
• 查看服务商状态页；
• 联系平台支持时提供 request id、时间、模型名、状态码、错误信息和最小复现请求。

---

十三、不同场景下的快速判断

1. 本地可以，服务器不行

优先检查：

• 环境变量；
• 服务器出站网络；
• 安全组；
• 防火墙；
• 代理；
• DNS；
• 证书库；
• 系统时间。

---

2. Postman 可以，代码不行

优先检查：

• SDK 配置；
• Header；
• 请求体序列化；
• 环境变量读取；
• 超时设置；
• 代理配置。

---

3. 非流式可以，流式不行

优先检查：

• SSE 支持；
• Nginx buffering；
• 网关超时；
• 客户端读取方式；
• 自定义网关是否支持 stream。

---

4. 昨天可以，今天不行

优先检查：

• 额度；
• 账单；
• Key 是否被撤销；
• 模型是否变更；
• 服务商状态页；
• 网关公告。

---

5. 小请求可以，大请求不行

优先检查：

• 上下文长度；
• 文件大小；
• 图片数量；
• 输出 token；
• 网关超时；
• RAG 拼接内容。

---

6. 单用户可以，并发一高就失败

优先检查：

• RPM；
• TPM；
• 并发限制；
• 连接池；
• 请求队列；
• 是否出现重试风暴。

---

7. 官方接口可以，自定义网关不行

优先检查：

• Base URL；
• Endpoint；
• 模型映射；
• 平台余额；
• 参数兼容性；
• 文件上传是否支持；
• 工具调用是否支持；
• stream 是否支持；
• 多模态输入是否支持。

---

十四、线上系统如何提高 AI API 调用稳定性

修好一次 API 报错只是第一步。如果要让线上系统稳定运行，需要提前设计重试、限流、降级和监控。

建议至少做到：

• 只对 408、429、500、502、503、504 和网络超时做有限重试；
• 对 400、401、403、404 不盲目重试；
• 使用指数退避和随机抖动，避免重试风暴；
• 设置请求队列，控制并发；
• 控制 prompt 长度和 token 消耗；
• 设置合理超时，并区分连接超时和读取超时；
• 给核心业务准备备用模型或备用供应商；
• 记录完整日志；
• 监控错误率、延迟、token 使用量、余额和额度。

推荐日志字段：

provider
base_url
model
endpoint
http_status
error_code
error_message
request_id
latency_ms
retry_count
trace_id
stream
fallback

有了这些信息，线上问题才能快速定位，而不是只能靠猜。

---

十五、总结：AI API 调用失败的优先排查顺序

可以按下面顺序排查：

1. 先看 HTTP 状态码和完整错误响应；
2. 401 查 API Key、Header 和环境变量；
3. 403 查账号权限、地区、项目和模型访问权限；
4. 404 查 Base URL、Endpoint 和模型名；
5. 400 / 422 查请求体、字段名、参数范围和接口格式；
6. 429 查限流、并发、余额、账单和额度；
7. 超时问题查输入长度、网络、代理、模型延迟和网关限制；
8. 500 / 502 / 503 / 504 查服务商状态，做有限重试或切换模型；
9. stream 问题单独查代理缓冲、SSE 支持和客户端读取方式；
10. 长期运行要补齐重试、限流、降级、日志、监控和告警。

大多数 AI API 调用失败并不神秘。只要把错误码、响应体、请求参数、运行环境和账号状态串起来看，绝大部分问题都能在较短时间内定位到真正原因。

如果需要稳定的官方渠道 Claude API，可以看下图。