问题排查 Claude Code 专题
API 连接失败怎么办：OpenAI、Anthropic、Gemini API 超时、401、403、429 的排查
AI API 连接失败的排查：区分网络层（超时、连接被拒、TLS）、认证层（401、403）、配额层（429）、服务层（5xx）四类错误，说明终端与代码中如何走代理、地区限制对 API 的影响，以及各类错误的处理。
API 调用失败的错误信息比网页版明确得多，按错误码分层处理，几乎不会走弯路。
按错误分层
| 错误 | 层 | 原因 | 处理 |
|---|---|---|---|
| Timeout、ETIMEDOUT | 网络 | 未走代理或节点不通 | 设代理、换节点 |
| ECONNREFUSED | 网络 | 代理端口错误或客户端未运行 | 核对端口 |
| TLS / certificate | 网络 | 证书或时间问题 | 见 TLS 错误 |
| 401 Unauthorized | 认证 | 密钥错误、过期 | 检查密钥 |
| 403 Forbidden | 地区 | 请求地区不受支持 | 换节点地区 |
| 429 Too Many Requests | 配额 | 速率或额度限制 | 等待、升级 |
| 500 / 502 / 503 / 529 | 服务 | 服务端故障或过载 | 重试 |
网络层
代码里的 HTTP 库（Python requests、Node fetch、Go net/http）默认不走系统代理，多数读取 HTTPS_PROXY 环境变量。
验证：
curl -I https://api.openai.com
curl -I https://api.anthropic.com
curl -I https://generativelanguage.googleapis.com返回状态码（即使是 4xx）说明网络通；超时说明没走代理。
设置：
export HTTPS_PROXY=http://127.0.0.1:7897端口以客户端为准。或开启 TUN 模式让所有进程自动走代理，见 AI 开发工具网络环境。
部分 SDK 需要在代码中显式传入代理配置，查阅对应 SDK 文档。
认证层：401
密钥错误、格式错误（多了空格或引号）、已被撤销、或用错了服务商的密钥。重新生成并检查环境变量读取是否正确。
地区层：403
OpenAI、Anthropic 的 API 同样有地区限制。403 在这里通常不是权限问题，而是请求的出口 IP 不在支持地区。换日本、新加坡、美国节点。香港节点会触发 403。
配额层：429
请求频率超过限制或额度用完。与网络无关。看响应头中的重试时间，或检查账户用量。免费层限制严格，付费后放宽。
服务层：5xx
服务端故障或过载（Anthropic 的 529 是过载）。查看官方状态页，指数退避重试。
长连接与流式响应
流式响应中途断开，多为节点抖动。换专线节点，策略组固定单节点，见 AI 稳定线路怎么选。
各服务商专项
常见问题
- API 连接超时是什么原因？
- 代码或终端没有走代理。设置 HTTPS_PROXY 环境变量，或开启 TUN 模式。用 curl 验证目标域名可达。
- API 返回 403 是什么意思？
- 在 OpenAI、Anthropic 的 API 场景下，403 常表示请求来源地区不受支持。换到日本、新加坡或美国节点。
- 网页版能用，API 调用失败？
- 网页走浏览器的系统代理，代码不走。给代码所在的进程设置代理环境变量，或开 TUN。