APIConnectionError、超时或完全没有响应
检查 同一个代理访问 ipinfo.io 有响应吗,客户端真的用了它吗?Python 里异常的 __cause__ 保存着底层错误。
处理 核对 HOST、PORT 和协议(Proxy302 的 HTTP 在 2222、SOCKS5 在 3333),再按第 2、3 步把代理传给客户端。
停止条件 如果 curl 不带密钥也连不上 API,问题在代理或网络,不在你的代码。
说清代理在 Claude API 客户端里放在哪、和 base_url 有什么不同,以及调用失败时怎么看报错。
base_url(或环境变量 ANTHROPIC_BASE_URL)决定 SDK 把请求发到哪台主机,Anthropic 的 Python 文档把它和 http_client 写在同一个构造函数里。代理决定请求走哪条网络路径到达这台主机。搜「Claude API 代理」的人,多数要的是后者。
只有在你自己搭的网关,或者你有权使用的网关上才改 base_url,因为你设置的主机会收到你的 API 密钥。别为了让地区报错消失,就把它指向不明主机。
| 项目 | 改变什么 | 文档里怎么写 |
|---|---|---|
| base_url / ANTHROPIC_BASE_URL | 请求发往的主机 | Python SDK 文档:base_url 参数或环境变量 |
| Python 代理 | 某一个客户端的网络路径 | http_client=DefaultHttpxClient(proxy=...) |
| Node 代理 | 某一个客户端的网络路径 | fetchOptions.dispatcher 配 undici 的 ProxyAgent |
| Claude Code | 命令行工具,不是 SDK | 代理变量和 settings.json:见 Claude Code 代理指南 |
来源:Claude Platform 的 Python 与 TypeScript SDK 文档,2026 年 11 月 17 日读取。SDK 文档没有列出 HTTPS_PROXY,所以请把代理直接传给客户端。
在要发请求的那台机器上运行。第 1 条必须显示你预期的国家。第 2 条故意不带密钥:官方文档里 401 authentication_error 对应密钥问题,所以返回 JSON 格式的 401 说明请求已到达 API(这是我们的理解)。第 3 条带上密钥,确认密钥经过代理也能用。
# 1) Which IP and country does Anthropic see? (the proxy's exit)
curl -x "http://USERNAME:PASSWORD@HOST:PORT" https://ipinfo.io/json
# 2) Does the request reach the API? No key on purpose: a JSON 401 authentication_error
# means the network path works and only the key is missing
curl -s -x "http://USERNAME:PASSWORD@HOST:PORT" https://api.anthropic.com/v1/messages \
-H "anthropic-version: 2026-10-21" -H "content-type: application/json" \
-d '{"model":"MODEL_ID","max_tokens":16,"messages":[{"role":"user","content":"Hello, Claude"}]}'
# 3) With your key: a normal message response (use a model ID from Anthropic's models page)
curl -x "http://USERNAME:PASSWORD@HOST:PORT" https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" -H "anthropic-version: 2026-10-21" \
-H "content-type: application/json" \
-d '{"model":"MODEL_ID","max_tokens":16,"messages":[{"role":"user","content":"Hello, Claude"}]}'把 HOST、PORT、USERNAME、PASSWORD 换成「我的资产」里的值,MODEL_ID 换成 Anthropic 模型页上的模型 ID。anthropic-version 的值取自 Anthropic 错误说明页。
Anthropic 的 Python 文档说 SDK 用 httpx2 发请求,要配代理就把自己的客户端作为 http_client 传进去。请用 DefaultHttpxClient,这样 SDK 默认的超时和连接设置都保留。独立 httpx 包里的客户端会抛 TypeError。
同一个客户端先请求 ipinfo.io,第 1 行输出就是 SDK 实际使用的出口。SDK 默认对连接错误、408、409、429 和 5xx 重试两次,示例改成一次,代理有问题时能更快报错。
# pip install anthropic (Python 3.10 or later; reads ANTHROPIC_API_KEY from the environment)
import anthropic
from anthropic import Anthropic, DefaultHttpxClient
PROXY = "http://USERNAME:PASSWORD@HOST:PORT" # percent-encode special characters in the password
http = DefaultHttpxClient(proxy=PROXY)
# 1) Which exit does this client use?
print(http.get("https://ipinfo.io/json").text)
# 2) Same client for the API. Leave base_url alone: this is a proxy, not a gateway.
client = Anthropic(http_client=http, max_retries=1, timeout=30.0)
try:
message = client.messages.create(
model="MODEL_ID", # a model ID from Anthropic's models page
max_tokens=16,
messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message.content[0].text, message._request_id)
except anthropic.APIConnectionError as e:
print("Could not reach the API through the proxy:", e.__cause__)
except anthropic.APIStatusError as e:
print("HTTP", e.status_code, e.response.headers.get("request-id"))
# SOCKS5: pip install "httpx2[socks]", then PROXY = "socks5://USERNAME:PASSWORD@HOST:PORT"把 HOST、PORT、USERNAME、PASSWORD 换成「我的资产」里的值。用 SOCKS5 时,安装 httpx2[socks] 并改用 socks5:// 那一行。
TypeScript 文档给出的 Node.js 做法:创建 undici 的 ProxyAgent,作为 fetchOptions.dispatcher 传入。undici 会用地址里的用户名和密码生成代理认证,并先做 URL 解码。Bun 用 fetchOptions.proxy,Deno 用 Deno.createHttpClient 的客户端,同一页都有示例。
// npm install @anthropic-ai/sdk undici (reads ANTHROPIC_API_KEY from the environment)
// Save as check.mjs and run: node check.mjs
import Anthropic from '@anthropic-ai/sdk';
import * as undici from 'undici';
// Wrap special characters of the password with encodeURIComponent()
const proxyAgent = new undici.ProxyAgent('http://USERNAME:PASSWORD@HOST:PORT');
const client = new Anthropic({
fetchOptions: { dispatcher: proxyAgent },
maxRetries: 1,
timeout: 30 * 1000,
});
try {
const message = await client.messages.create({
model: 'MODEL_ID', // a model ID from Anthropic's models page
max_tokens: 16,
messages: [{ role: 'user', content: 'Hello, Claude' }],
});
console.log(message.content[0].text, message._request_id);
} catch (err) {
if (err instanceof Anthropic.APIError) console.log(err.status, err.name);
else console.log('Network error:', err.message);
}
// SOCKS5: new undici.ProxyAgent('socks5://USERNAME:PASSWORD@HOST:PORT')把占位符换成「我的资产」里的值。用 SOCKS5 时,改用最后一行注释里的 socks5:// 地址。
检查 同一个代理访问 ipinfo.io 有响应吗,客户端真的用了它吗?Python 里异常的 __cause__ 保存着底层错误。
处理 核对 HOST、PORT 和协议(Proxy302 的 HTTP 在 2222、SOCKS5 在 3333),再按第 2、3 步把代理传给客户端。
停止条件 如果 curl 不带密钥也连不上 API,问题在代理或网络,不在你的代码。
检查 密码里有没有未编码的特殊字符,或者这个 IP 的租期是否已到期?
处理 对 URL 里的密码做百分号编码,或重新从「我的资产」复制,并看一下到期日。
检查 Anthropic 的错误说明把 401 对应到 API 密钥:格式不对、已撤销或已过期。
处理 到 Claude Console 检查密钥。收到 401 说明请求已经到达 Anthropic,代理本身是通的。
检查 错误说明页把 403 描述为密钥无权使用该资源,没有列出专门针对地区的错误。这个密钥是不是限定在你没有调用的工作区或资源上?
处理 到 Console 里检查组织和工作区权限。另外,把第 1 步看到的出口国家和支持地区清单对照一下。
停止条件 如果出口国家不在清单里,任何客户端设置都改变不了这一点。请只在受支持的地区使用 API。
检查 429 是速率或额度上限,529 是临时过载,500 和 504 是 Anthropic 一侧的错误。
处理 这些都不是代理的问题。SDK 已经自动重试两次;错误持续时记下 request-id 响应头,联系 Anthropic 支持时附上。
Anthropic 公布了支持的国家、地区和属地清单,并说明未列出的一律不支持。政策还涉及实际身处不支持地区的人,以及在当地注册、总部设在当地或多数股权在当地的公司。代理改变的是网络出口,不会改变这些规定。
错误说明页和政策页都没有写清请求的位置怎么判断,也没有列出专门针对地区的错误码。所以出口国家只是要检查的一项,不是保证:用代理访问 ipinfo.io 读出它,对照清单,并且只在允许的地区使用 API。账号方面(手机号、账单所在国)请看 Claude 地区指南。
打开 Claude 专用页面,选一个所在国家在 Anthropic 清单上的 IP。静态 ISP IP 30 天 US$7.99,各国同价;订单页会显示当天哪些国家有货。
打开「我的资产」,复制 HOST、PORT、USERNAME 和 PASSWORD。每个 IP 只有一种协议,购买时选定:HTTP 用 2222 端口,SOCKS5 用 3333 端口。
运行第 1 步的三条 curl 命令,再把代理填进 Python 或 Node 客户端。一个账号固定用一条 IP,并遵守 Anthropic 的条款和支持地区。
预期结果 第 1 条显示你买的国家,第 2 条返回 JSON 格式的 401。
不需要。ANTHROPIC_BASE_URL 设置的是 SDK 调用的主机,代理要传给 HTTP 客户端,Python 和 TypeScript 文档都是这么写的。只有在你自己搭的或有权使用的网关上才改 base_url。
我们读到的 SDK 文档没有列出它,所以请把代理直接传给客户端。Claude Code 是另一个工具,它的代理变量有文档说明,见 Claude Code 代理指南。
HTTP 最简单,两个代码示例都直接支持。SOCKS5 在 Python 里需要 httpx2[socks],在 Node 里用 undici 的 ProxyAgent,但前提是你买的 IP 本来就是 SOCKS5。
不一定。Anthropic 的错误说明把 403 描述为密钥无权使用该资源,没有列出专门针对地区的错误。先查密钥权限,再把出口国家和支持清单对照。
不能。代理只改变网络出口。Anthropic 的支持地区清单和政策依然适用,而且政策还涉及人实际所在的位置。
官方文档 · 确认日期:
2026 年 11 月 17 日读取:SDK 用 httpx2 发请求;base_url 或环境变量 ANTHROPIC_BASE_URL;http_client=DefaultHttpxClient(proxy=...);建议用 DefaultHttpxClient 而不是裸客户端;传入独立 httpx 包的客户端会抛 TypeError;默认自动重试两次(max_retries);APIConnectionError 与 APIStatusError;_request_id 属性。
页面没有说明 SDK 是否读取 HTTP_PROXY、HTTPS_PROXY。
官方文档 · 确认日期:
2026 年 11 月 17 日读取:Configuring proxies 一节:Node.js 里创建 undici.ProxyAgent,作为 fetchOptions.dispatcher 传入;Bun 用 fetchOptions.proxy,Deno 用 Deno.createHttpClient 的客户端;maxRetries(默认 2)和 timeout 选项;超时时抛 APIConnectionTimeoutError。
官方文档 · 确认日期:
2026 年 11 月 17 日读取:400 invalid_request_error、401 authentication_error(密钥问题)、402 billing_error、403 permission_error(密钥无权使用该资源)、404、413、429 rate_limit_error、500 api_error、504 timeout_error、529 overloaded_error;错误响应是带 request_id 的 JSON;响应头 request-id;SDK 默认按指数退避重试两次。
页面里没有专门针对国家或地区的错误。
官方文档 · 确认日期:
2026 年 11 月 17 日读取:Anthropic 可支持访问的国家、地区和属地清单,例如日本、新加坡、英国、美国;乌克兰在清单中,但克里米亚、顿涅茨克、卢甘斯克除外。
官方文档 · 确认日期:
2026 年 11 月 17 日读取:未列出的国家和地区一律不支持;政策涉及实际身处不支持地区的人,以及在当地注册、总部设在当地或多数股权在当地的机构。页面没有说明如何判断位置,也没有提到代理。
官方文档 · 确认日期:
2026 年 11 月 17 日读取:创建客户端时的 proxy 参数;账号密码写在代理 URL 的 userinfo 部分;SOCKS 需要 pip install 'httpx2[socks]' 和 socks5:// 地址。
官方文档 · 确认日期:
2026 年 11 月 17 日读取:传给 ProxyAgent 的字符串或 URL 就是代理地址;没有 token 或 auth 时,proxy-authorization 头由 URI 里的用户名和密码生成,并先做 URL 解码;socks5: 地址由 Socks5ProxyAgent 处理。
产品观察 · 确认日期:
站点产品信息文件,11 月 10 日对照控制台、后端和价格表核对:静态 ISP 按 IP 租用,30 天 US$7.99,各国同价;HTTP 端口 2222、SOCKS5 端口 3333;每个 IP 一种协议;没有免费试用。
注册账号、充值一次,就能选动态住宅、静态 ISP 或数据中心 IP,几分钟配进你的浏览器。