Claude Code 403、503、529 报错：按来源排查

Claude Code 屏幕上的 403、503、529 不一定是 Anthropic 返回的。请求从你的电脑发出，可能先经过本机代理、公司代理、中转站或自建网关，任何一层都能回你这几个状态码，修法取决于到底是哪一层。判断只需要两样东西：完整的报错原文，以及 /status 里有没有 Anthropic base URL 这一行。

• 没有这一行：请求直接发给 Anthropic（配置了 Bedrock 等云平台的除外）。这时 403 出在网络出口、所在地区或账号权限上；529 是 Anthropic 某个模型容量不足，不扣你的额度；503 不在 Anthropic API 的错误列表里，只有 Anthropic 发布了故障公告时才算到它头上。
• 有这一行：每个请求、每个错误都先经过那个地址。No available accounts、No available channel、No available provider found、no available server 这类 503 是中转或网关自己的状态，重装 Claude Code、重新登录都改变不了，要找它的运营方。

先确认请求发给了谁

在 Claude Code 会话里输入 /status，它会打开 Status 标签页，看两行：

• Anthropic base URL：只有设置了网关地址（ANTHROPIC_BASE_URL）时才出现，显示的就是请求实际去往的地址。没有这一行，说明这次会话没有拿到网关变量。
• Auth token、API key 或 Login method：前两种说明用的是变量里的密钥（通常是中转或网关发的令牌），Login method 说明用的是 claude.ai 账号登录。

同一个变量既在 shell 里 export 过、又写在 ~/.claude/settings.json 的 env 块里时，以设置文件里的值为准。"我在终端里改过了"不等于生效，/status 显示的才是这次会话真正在用的配置。

报错末尾那句话也能帮你判断，但和版本有关。当前版本遇到 5xx 时，末尾会指出去哪里查服务状态：直连 Anthropic 写 check https://status.claude.com，设置了自定义 ANTHROPIC_BASE_URL 则写成 check your inference gateway (网关域名)。旧版本不是这样：在 Claude Code 2.1.137 上，有用户经账号池中转收到 503 No available accounts，末尾照样写着 check status.claude.com。所以末尾那句只作参考，判断以 /status 为准；版本太旧就先运行 claude update。

如果回来的是一张网页而不是 API 的 JSON，Claude Code v2.1.281 起会显示状态码加网页标题，例如 API Error: 502 Bad Gateway。这种形式说明回答你的是中间的代理、负载均衡或网关。

用 VS Code 或 Cursor 插件的话，插件进程和终端里的 claude 可能拿到不同的环境变量（原因见下文），终端里 /status 的结果不能直接代表插件。两边共用的是 ~/.claude/settings.json，把关键变量写在那里，两边的状况才一致。

按报错原文找到对应的一层

同一个状态码在表里出现多次，区别就在后半句原文和 /status 那一行。下面按状态码展开每一类的判断依据和修法。

403：网络出口、账号，还是中间那一层

浏览器能开 claude.ai，终端或插件却报 403

浏览器走的是系统代理设置，Claude Code 读的是环境变量：https_proxy、HTTPS_PROXY、http_proxy、HTTP_PROXY，按这个顺序取第一个设置了的，另外支持 NO_PROXY。系统代理开着、终端里没有这些变量，Claude Code 的请求就不会经过你配置的代理，出口不同，结果也就不同。

在启动 Claude Code 的同一个终端里检查：

env | grep -i _proxy
curl -I https://api.anthropic.com

curl 能拿到任何 HTTP 状态行，就说明请求到达了 Anthropic；拿到 403，Claude Code 官方排障文档给出的解释是代理或网络过滤拦下了这个主机，或者 Claude Code 在你所在的地区不可用；没有输出或超时，是连接层面的问题，按 Claude Code Unable to connect to API：ECONNREFUSED、ECONNRESET 与代理错误排查 处理。Windows PowerShell 里要写 curl.exe -I，否则会调用内置的 Invoke-WebRequest。

需要让 Claude Code 使用公司或本机的 HTTP 代理时，注意两点：

• Claude Code 不支持 SOCKS 代理，socks5:// 开头的地址不生效，要填 HTTP 代理地址。代理需要账号密码时写成 http://username:password@proxy.example.com:8080。
• 想让终端和插件一致，写进 ~/.claude/settings.json：

{
  "env": {
    "HTTPS_PROXY": "http://proxy.example.com:8080"
  }
}

终端能用、VS Code 或 Cursor 插件报 403，多半是编辑器没有继承 shell 的环境变量：从 Dock、开始菜单或桌面图标启动的 VS Code，拿不到你在 .zshrc 里 export 的变量。官方给的办法是在终端里进入项目目录，用 code . 启动 VS Code；更稳的是上面这种写进 ~/.claude/settings.json 的方式，它由插件和 CLI 共用。插件设置里也有 environmentVariables 一项，可以单独给 Claude 进程设变量。Cursor 装的是同一个插件，处理方式相同。

所在地区不在支持名单里

截至 2026 年 9 月 29 日，Anthropic 的支持国家和地区列表不包含中国大陆、香港和澳门。在官方直连这条路上，地区导致的 403 是使用资格问题，不是本机配置问题：安装时看到 App unavailable in region 也是同一回事。改环境变量、换终端、重新登录都改变不了资格，用不受支持地区的身份使用官方服务还可能牵连账号。

这种情况下该做的是停止在官方直连上反复尝试，换一条你所在地区可以使用的接入方式。可选的路线（云平台、中转、替代工具）和各自的取舍见 Claude Code 国内使用指南：安装、注册、中转和稳定接入怎么选。

登录后出现 Request not allowed

完整报错是 API Error: 403 {"error":{"type":"forbidden","message":"Request not allowed"}}。官方给的检查顺序：

1. Claude Pro / Max 用户：到 claude.ai/settings 确认订阅仍然有效。
2. 用 Anthropic Console 账号登录的：确认账号有 "Claude Code" 或 "Developer" 角色，由管理员在 Console 的 Settings → Members 里分配。
3. 在代理后面使用的：代理可能干扰 API 请求，回到上一节检查代理变量。

三项都确认后，用 /logout 再 /login 重新走一遍登录。不要照搬 rm -rf ~/.claude 的做法：这个目录里有你的设置、会话记录和登录凭证，删掉后这些都要重建，而网络出口、地区和账号角色一样都不会变，403 照旧。

如果登录页直接显示 Authorization failed 和 Claude Code access has not been granted for this account. Contact your administrator.，说明你所在的 Claude 企业版组织把你设成了自定义角色，而分给你所在组的自定义角色都不含 Claude Code。这只能由组织 Owner 在角色设置里调整，改好后重新运行 claude 登录即可。

走网关或中转时的 403

/status 里有 base URL 时，403 先要看是谁说的：

• 返回的是 HTML 页面，网关日志里却没有这次请求：网关前面的 Web 应用防火墙或反向代理拦下了请求体。Claude Code 的请求里有 XML 风格的标签和源代码，容易命中防 XSS 的请求体规则，于是出现一个奇怪的现象：用 curl 发一句短测试能通，真正干活时就 403。修法在网关一侧：对 /v1/messages 取消请求体检查，例如 AWS WAF 的 CrossSiteScripting_Body 规则、nginx ModSecurity 的 OWASP CRS 请求体规则。
• 返回的是中转自己的 JSON：有些中转会限制客户端或令牌权限，例如返回 This service is restricted to the official Claude Code client.。这是中转的规则，Anthropic 文档里没有这条错误，按中转文档调整或问运营方。
• 企业通过 Claude apps gateway 登录：看到 Gateway refused the request · signing in again won't change this 时，拒绝来自网关或它背后的上游，重新登录没用，找网关管理员查审计日志。

这些 403 和 API 无关

• Claude 用 WebFetch 读网页时报 403：拒绝它的是那个网站或它前面的 CDN（例如 Cloudflare 的防爬规则），你的 Claude Code 权限没有问题。换一个来源，或者把页面内容复制给它。
• 安装脚本报 curl: (22) The requested URL returned error: 403，或下载到一张写着 App unavailable in region 的网页：这是下载地址被拦截或地区不支持，发生在安装阶段，和运行时的 API 403 分开处理。

503：官方 API 错误列表里没有它

Anthropic 的 Messages API 错误列表只有 400、401、402、403、404、409、413、429、500、504 和 529，没有 503，过载用的是 529。所以在 Claude Code 里看到 503，第一反应应该是看 /status：有 base URL，503 基本出自你调用的那个中转或网关；Claude Code 碰到服务器错误时本来就会自动重试最多 10 次，你看到报错时重试已经失败，反复按回车改变不了中转那边的配置。

各类 503 原文对应的含义：

• No available accounts：开源账号池中转 sub2api 的源码里，这条 503 表示能服务这个模型的账号暂时都用不了（被限流、额度自动暂停或被临时屏蔽），或者你的分组里根本没有账号；分组里有账号但没有一个配置了你请求的模型时，它返回的是 404 model_not_found。其他中转软件也可能用同样的说法。短时耗尽等几分钟可能恢复，持续出现就把原文发给运营方。
• No available channel for model 模型名 under group 分组名：new-api 类中转的报错，意思是这个中转在你的分组里没有能跑这个模型的渠道。一个真实例子是：用户在中转充值后用 claude-opus-5 报 503 No available channel for model claude-opus-5 under group default，末尾写着 check your inference gateway (api.sooloa.com)。中转还没给你的分组开通某个新模型时就会这样：先用 /model 换成该中转列出的模型，或者问运营方什么时候开通、要不要换分组。new-api 项目明确要求第三方托管站的问题联系其运营方，去它的 GitHub 提 issue 解决不了。
• No available provider found：Claude Code Hub 的报错，原因是所有供应商被禁用、熔断器全部处于打开状态、分组限制匹配不上或并发达到上限。自己部署的到管理后台的"供应商管理"里查；用别人部署的，找部署者。
• no available server：这是反向代理 Traefik 在负载均衡后面没有健康后端时返回的固定文字（503）。Anthropic 的文档里没有这句话，看到它基本可以推断：你调用的中转或自建网关的后端服务停了或正在重启。自建的查容器状态和健康检查；用中转的，稍等几分钟再试，持续出现就把时间和原文发给运营方。
• no healthy upstream：这句话是反向代理 Envoy 的标准文字，有 Claude Code 用户在 Anthropic 服务异常期间也报告过。只有 /status 没有 base URL、status.claude.com 上正好有故障公告时，才把它当作 Anthropic 那边的问题并等待恢复；否则按中转或网关的问题处理。

如果你用的是直连、/status 没有 base URL，状态页也没有故障，却持续看到 503，检查是否有公司代理或其他网关夹在中间，末尾那句会写出它的主机名。

529：Anthropic 容量不足，不是你的额度

API Error: Repeated 529 Overloaded errors. The API is at capacity 的意思是 Anthropic 暂时没有容量服务所有用户。弹出这条之前，Claude Code 已经按指数退避重试过最多 10 次。官方说明写得很清楚：529 不是你的用量限制，也不计入你的配额。

容量按模型计算，所以最快的办法是运行 /model 换一个模型继续工作；Claude Code 有时也会主动提示，例如 Opus is experiencing high load, please use /model to switch to Sonnet。不急的话，看看 status.claude.com 或末尾写的状态页，几分钟后再试。

经中转使用时也可能看到 529，这通常是上游的过载被原样转了回来，中转本身不会凭空多出 Anthropic 的容量。备用模型链、CI 里让它一直等之类的处理方式，见 Claude Code 报 529 过载怎么办：换模型还是等待；报错打断了正在进行的任务、担心续接时重复执行，见 Claude Code 500 和 529：宕机后怎样安全续接而不重复工作。遇到的是 500 而不是 529，看 Claude Code 出现 API Error 500？先分清故障分支，再修 Internal Server Error。

用一次最小请求确认问题在不在中转

/status 显示了 base URL 时，可以绕开 Claude Code，直接对网关发一个只要 1 个 token 的请求。先在 shell 里 export 好 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN（下面的命令读的是 shell 变量，只写在设置文件里不够），然后运行：

curl -sS -w '\n%{http_code}\n' -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

结果这样读：

• 返回以 {"id":"msg_ 开头、带 content 的 JSON：地址和令牌都没问题，问题出在 Claude Code 这一侧的配置上，回头查 /status 和 ~/.claude/settings.json。
• 报"模型不存在"之类的错误：同样说明地址和令牌可用，只是这个中转不叫这个模型名，把 model 换成它列出的名字再测。
• 401：令牌被拒，去中转控制台重新复制或生成。
• 和 Claude Code 里一样的 503 或 403：问题在中转或网关本身，和 Claude Code 无关。

如果中转要求把密钥放在 x-api-key 请求头里，把 Authorization 那一行换成 -H "x-api-key: $ANTHROPIC_API_KEY"。

还有一种情况值得排除：你以为自己是直连，/status 却出现了 base URL。这通常是以前试过中转，ANTHROPIC_BASE_URL 还留在 shell 配置或设置文件的 env 里。删掉它，开一个新终端再启动 Claude Code。变量、令牌和设置文件的完整写法见 Claude Code API 配置：先选路由，再设置 Key、模型和网关。

什么时候该停手，找谁，带什么

下面这些情况，继续改本机配置没有意义：

• 地区不在支持列表里，却在走官方直连：换路线。
• 报错来自中转或网关（503 的 No available …、中转 JSON 403、HTML 403 且网关没收到请求）：找运营方或管理员。
• 企业版角色未授权，或 Gateway refused the request：找组织 Owner 或网关管理员。
• 直连时的 529、no healthy upstream，且状态页有公告：等待，或 /model 换模型。

联系对方时带上这些，对方才能查到具体请求：

1. 完整报错原文，包括末尾那句和 request id（new-api 类中转的报错里会带）。
2. 出错的时间（精确到分钟和时区）和使用的模型名。
3. claude --version 的输出。
4. /status 里 Anthropic base URL 和认证方式那两行，令牌只保留前后几位。
5. 上一节 curl 测试的状态码和返回内容。

直连 Anthropic、状态页没有公告、错误却一直持续时，在 Claude Code 里运行 /feedback，它会附上请求详情供 Anthropic 调查。插件本身的界面或登录问题，参考 Claude Code 在 VS Code 里用不了？先定位失败表面。

需要换接入路线时

官方直连因为地区不可用时，一种替代是通过兼容 Anthropic Messages 格式的网关接入。以老张API为例，它提供 Anthropic Messages 兼容的 /v1/messages 接口，在 ~/.claude/settings.json 里这样配置：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.laozhang.ai",
    "ANTHROPIC_AUTH_TOKEN": "sk-你的老张API密钥"
  }
}

配置后，/status 的 Anthropic base URL 一行会显示 https://api.laozhang.ai。它本身也是一个中转：出错时同样按上面的方法判断，503、403 先看是不是它这一层返回的，用上面的 curl 测试确认。它也不会给 Anthropic 增加容量，上游 529 时照样需要换模型或等待。请求格式与认证方式见 老张API 文档，其他路线的比较见 Claude Code 国内使用指南：安装、注册、中转和稳定接入怎么选。

常见问题

报 403 是不是账号被封了？ 不一定。官方对 Request not allowed 列出的原因是订阅状态、账号角色和代理干扰，在不受支持的地区直连也会 403。先按上面的顺序确认网络出口、地区和角色，不要一看到 403 就注册新账号或清空 ~/.claude。

503 是 Anthropic 挂了吗？ 多数时候不是。Anthropic 的 API 用 529 表示过载，错误列表里没有 503。/status 里有 base URL 时，503 基本来自那个中转或网关；只有直连、而且 status.claude.com 上有故障公告时，才是 Anthropic 那边的问题。

要不要重装 Claude Code？ 这三类报错都不是安装损坏引起的，重装解决不了。唯一和版本有关的是：旧版本的报错末尾不会写出网关主机名，升级后判断会更容易。

529 会不会一直扣我的额度？ 官方说明 529 不计入你的用量配额。经中转使用时怎么计费，以中转自己的说明为准。