API 调用异常自查指南：连接失败 / 报错 / 无响应先看这里

把这份指南收藏到浏览器书签里，下次遇到 API 调不通先打开它，再去翻日志。根据我们的客服后台数据，绝大多数"API 出问题了"的工单，最后定位都不在 API 本身，而是几类高度重复的本地环境与配置错误。本文把它们按排查优先级排成一份清单，从最常见的开始一项一项过。

建议读者：手边打开你的代码或 SDK 配置，对照清单边看边查。

故障定位的核心思路

调用 Claude API 时一次请求会经过四个环节：

你的代码 → 本地网络（代理/DNS） → 接口网关 → 模型服务

你的代码 → 本地网络（代理/DNS） → 接口网关 → 模型服务

任何一个环节断了，最终现象都是"调不通"，但解决方案完全不同。所以排查的顺序不能颠倒，必须从离自己最近的环节开始往外查：网络 → 接口地址 → 鉴权 → 请求体 → 服务端。

下面按这个顺序逐项展开。

一、先确认网络环境

客服话术：您可以先按这一节自查一下网络和接口配置。很多连接失败、超时、无响应的问题，通常是本地代理节点、DNS 或接口地址不匹配导致的，调整一下就好。

1. 是否开启了代理软件

最常见的一类问题：本地开着 Clash / Surge / 小火箭 / V2Ray / 各种 VPN，结果代理软件把发往国内网关的请求也吞了。

请先检查这些软件是否在运行：

• Clash（Clash for Windows / ClashX / Clash Verge）
• Surge
• Shadowrocket（小火箭）
• V2RayN / Qv2ray
• 各类商业 VPN 客户端
• 公司统一下发的网络管控/审计代理

如果开启了，先看下一小节怎么调。如果没开，直接跳到第 3 小节。

2. 开了代理怎么办：四种调整方式按顺序试

下面以国内用户最常用的 Clash Verge 为例演示（ClashX、Clash for Windows 操作路径类似；Surge / Shadowrocket 后面给出对应位置）。按顺序逐个尝试，遇到能通的就停。

方式 A：切换节点

代理软件里换一个节点（特别是从香港/新加坡节点切到日本/美国，或者反过来）。某些节点对国内网关的解析路径不健康，换一个立即恢复。

方式 B：在 Clash Verge 首页切到「直连」模式（最快验证）

最快验证"是不是代理搞的鬼"的方法：把代理模式切到 直连（DIRECT），让所有流量都走本地直接出去。

操作路径：打开 Clash Verge → 首页 → 右上角「代理模式」面板 → 点 直连。

切完点一下「当前节点」上方刷新一下生效。如果这时候 API 就能通了，说明就是代理规则把请求拦截/绕路了，回到方式 D 加白名单。

Surge：右上角档位 → Direct；Shadowrocket：底部 → 直连。

方式 C：试试「全局」模式

代理软件默认是「规则」模式，按域名白名单走代理。如果规则没有把国内网关域名加进直连白名单，请求可能被错误地走到海外节点再绕回来，导致超时。

切到 全局（Global） 模式先验证一下（同样在首页代理模式面板里），能通就再回去调规则。

Surge：右上角档位 → Global；Shadowrocket：底部 → 全局路由。

方式 D：在订阅规则里加直连白名单（推荐长期方案）

这是客服最常给的标准方案，不影响你其他需要代理的网站，只把 API 域名加到直连。Clash Verge 完整步骤：

第 1 步：左侧菜单 → 订阅 → 找到你正在使用的订阅 → 鼠标右键（或点订阅卡片右上角菜单按钮） → 选 编辑规则。

第 2 步：在「编辑规则」面板里：

• 规则类型 选「匹配域名后缀 (DOMAIN-SUFFIX)」
• 规则内容 输入 claudeapi.com
• 代理策略 选「直接连接 (DIRECT)」
• 点击下方的 添加前置规则 按钮

一定要点「前置规则」而不是「后置规则」——前置会被优先匹配，否则可能被你订阅里前面的其他规则截胡。

第 3 步：保存。可以在规则列表里看到 claudeapi.com DOMAIN-SUFFIX DIRECT 已经生效（绿色高亮）：

第 4 步（可选但推荐）：检查一下「设置」里有没有开启 TUN 模式 / 虚拟网卡模式 或者 系统代理。如果你只是命令行调 API、不需要代理软件接管系统流量，建议把这两项关掉，避免它们绕过规则把请求劫走：

加完规则后访问 API 就会绕过代理走本地直连，长期稳定。其他需要科学上网的网站不受影响。

如果你用的是 Clash for Windows / ClashX / Surge / 小火箭，原理一致：找到「规则」配置文件，把 DOMAIN-SUFFIX,claudeapi.com,DIRECT 加在规则列表最前面，保存重启即可。Surge 的话直接在 [Rule] 节顶部加这一行。

3. 国内 / 海外服务器，分别选哪个接口

部署位置不同，接口地址应该不同：

简而言之：部署在哪里就让请求从哪里直发，少绕弯。绕得越多越容易在某一跳超时。

4. DNS 也要看一眼

少数环境下问题出在 DNS 解析：

# Linux / macOS
nslookup gw.claudeapi.com

# Windows
nslookup gw.claudeapi.com 8.8.8.8

# Linux / macOS
nslookup gw.claudeapi.com

# Windows
nslookup gw.claudeapi.com 8.8.8.8

如果返回 *** Can't find ... 或解析到一个明显不对的 IP（比如 127.0.0.1），说明你的 DNS 被劫持或者本地 hosts 写错了。建议把系统 DNS 临时改成 223.5.5.5（阿里）或 119.29.29.29（DNSPod），再试一次。

二、确认接口地址是否填对

网络没问题之后，第二大类问题就是 Base URL 写错。这一类故障的特征是：能拿到 HTTP 响应（不是连接失败），但响应内容是 404、403 或一坨 HTML，而不是 JSON。

1. Base URL 必须用对

不同接入方式对应不同的 Base URL，别把这两个混着填：

重点提醒：

• OpenAI 兼容方式必须带 /v1 后缀，否则会 404
• Anthropic 原生方式不要加 /v1，SDK 会自己拼接路径
• 不要在末尾多加 /，比如 https://gw.claudeapi.com/ 多一个斜杠在某些 SDK 里会出问题

2. 三种语言的正确写法

Python（Anthropic 原生）：

from anthropic import Anthropic

client = Anthropic(
    base_url="https://gw.claudeapi.com",
    api_key="sk-你的密钥",
)

resp = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.content[0].text)

from anthropic import Anthropic

client = Anthropic(
    base_url="https://gw.claudeapi.com",
    api_key="sk-你的密钥",
)

resp = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.content[0].text)

Python（OpenAI 兼容）：

from openai import OpenAI

client = OpenAI(
    base_url="https://gw.claudeapi.com/v1",   # 注意带 /v1
    api_key="sk-你的密钥",
)

resp = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)

from openai import OpenAI

client = OpenAI(
    base_url="https://gw.claudeapi.com/v1",   # 注意带 /v1
    api_key="sk-你的密钥",
)

resp = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)

Node.js / TypeScript（Anthropic 原生）：

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  baseURL: "https://gw.claudeapi.com",
  apiKey: process.env.CLAUDE_API_KEY,
});

const resp = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [{ role: "user", content: "你好" }],
});
console.log(resp.content[0].text);

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  baseURL: "https://gw.claudeapi.com",
  apiKey: process.env.CLAUDE_API_KEY,
});

const resp = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [{ role: "user", content: "你好" }],
});
console.log(resp.content[0].text);

cURL（最快的连通性测试）：

curl https://gw.claudeapi.com/v1/messages \
  -H "x-api-key: sk-你的密钥" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 64,
    "messages": [{"role":"user","content":"ping"}]
  }'

curl https://gw.claudeapi.com/v1/messages \
  -H "x-api-key: sk-你的密钥" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 64,
    "messages": [{"role":"user","content":"ping"}]
  }'

排查时强烈建议先用 cURL 验证一次：cURL 通了，说明账号、网关、Key 都没问题，问题就在你的 SDK 配置；cURL 不通，问题在网络或 Key。

3. 配置项常见笔误清单

最后 30 秒过一眼这张表，能在重启 IDE 之前救你一命：

三、API Key 与鉴权头

网络通了、Base URL 也对了，下一个高频翻车点是 鉴权。

1. Key 本身

• Key 必须以 sk- 开头，完整粘贴，不要带前后空格
• 不要把 Key 写在前端代码或公开仓库里，一旦泄漏请立即在控制台撤销并重新生成
• 同一个 Key 在多端共用没问题，但请求量会合并计费

2. 鉴权头怎么放

不同 SDK 用的请求头不一样，看清楚再填：

常见错误：

• OpenAI 兼容路径忘了 Bearer 前缀，会返回 401
• Anthropic 原生用了 Authorization: Bearer ...，部分版本会返回 401 或 403
• Key 包含换行符（从富文本里复制带来的），表现为 401 但你死活看不出来

3. 一行命令验证 Key 是否有效

curl https://gw.claudeapi.com/v1/messages \
  -H "x-api-key: sk-你的密钥" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-haiku-4-5-20251001","max_tokens":16,"messages":[{"role":"user","content":"hi"}]}'

curl https://gw.claudeapi.com/v1/messages \
  -H "x-api-key: sk-你的密钥" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-haiku-4-5-20251001","max_tokens":16,"messages":[{"role":"user","content":"hi"}]}'

• 返回 JSON 且 content 有内容 → Key 有效，问题在你的应用代码
• 返回 401 invalid x-api-key → Key 错了或被撤销
• 返回 403 → Key 有效但权限/余额有问题，去控制台看一眼

四、请求体与模型 ID

到这一步，请求已经能发出去也能拿到响应了，但响应是错的。常见原因：

1. 模型 ID 写错

只使用以下几个 ID（其他全部会 404）：

写成 claude-3-opus、claude-3.5-sonnet、gpt-4 这些都会失败。

2. 必填字段缺失

Anthropic 原生最常见的坑：忘记 max_tokens，服务端直接返回 400。

3. 消息结构

messages 数组里每条必须有 role 和 content，role 只能是 user 或 assistant（系统提示词在 Anthropic 里通过顶层 system 字段传入，不放在 messages 里）。

五、还是不行？最后两招

走到这里都没解决，做这两件事：

1. 打开 SDK 的 debug 日志

Python：

import logging
logging.basicConfig(level=logging.DEBUG)

import logging
logging.basicConfig(level=logging.DEBUG)

Node：

DEBUG=* node your_script.js

DEBUG=* node your_script.js

看具体是哪一跳出问题：DNS / TLS 握手 / HTTP 请求 / 响应解析。

2. 把以下信息发给客服

只有这些信息齐了，客服才能快速定位：

1. 完整的报错信息（包括 HTTP 状态码、响应体）
2. 你用的 Base URL（截图你的配置文件那一行）
3. 你用的 SDK 与版本（pip show anthropic 或 npm list @anthropic-ai/sdk）
4. 是否开启代理、代理软件名称
5. 同一时刻 cURL 能否通

控制台见 console.claudeapi.com，文档与定价见 claudeapi.com。

一张图总结

报错了？
  │
  ├─ 连接失败 / 超时 / 无响应 ──→ 排查 1：网络环境（代理、DNS、节点）
  │
  ├─ 拿到 HTML / 404 / 405      ──→ 排查 2：Base URL 是否填对
  │
  ├─ 401 / 403                  ──→ 排查 3：API Key 与鉴权头
  │
  ├─ 400 + 字段错误             ──→ 排查 4：请求体 / 模型 ID
  │
  └─ 时通时不通 / 5xx           ──→ 排查 5：debug 日志 + 联系客服

报错了？
  │
  ├─ 连接失败 / 超时 / 无响应 ──→ 排查 1：网络环境（代理、DNS、节点）
  │
  ├─ 拿到 HTML / 404 / 405      ──→ 排查 2：Base URL 是否填对
  │
  ├─ 401 / 403                  ──→ 排查 3：API Key 与鉴权头
  │
  ├─ 400 + 字段错误             ──→ 排查 4：请求体 / 模型 ID
  │
  └─ 时通时不通 / 5xx           ──→ 排查 5：debug 日志 + 联系客服

把这份清单按顺序走一遍，90% 的 API 调用问题在第二步之前就能解决。剩下 10%，把上面"联系客服"那一节列的五项信息整理齐了一起发过来，比来回截图问 10 句快得多。