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

> 403、503、529 不一定是 Anthropic 返回的。先看 /status 有没有 Anthropic base URL：没有就查网络、地区和账号，有就先查中转或网关。

- URL: https://blog.laozhang.ai/zh/posts/claude-code-403-503-529-errors
- Published: 2026-09-29
- Updated: 2026-09-29
- Author: LaoZhang AI Team (https://blog.laozhang.ai/zh/about)
- Category: Claude Code
- Tags: 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`，把关键变量写在那里，两边的状况才一致。

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

| 报错原文（关键部分） | 返回错误的一方 | 先做什么 |
| --- | --- | --- |
| `API Error: 403 {"error":{"type":"forbidden","message":"Request not allowed"}}`，`/status` 无 base URL | Anthropic：订阅、角色、网络出口或地区不被接受 | 查订阅和角色，在同一终端测 `curl -I https://api.anthropic.com` |
| 登录时出现 `OAuth error` 或 `403 Forbidden` | Anthropic 登录环节 | 同上；远程 SSH 时确认授权链接在本机浏览器打开 |
| `Claude Code access has not been granted for this account` | 企业版组织的角色设置 | 找组织 Owner 分配含 Claude Code 的角色 |
| `403` 加 HTML 页面（如 `403 Forbidden`），`/status` 有 base URL | 网关前面的防火墙或反向代理 | 让网关管理员对 `/v1/messages` 取消请求体检查 |
| 中转返回的 JSON 403（如 `restricted to the official Claude Code client`） | 中转站自己的访问规则 | 看中转文档或联系运营方 |
| 让 Claude 读网页时抓取失败、提示 403 | 被抓取的网站 | 与 API 无关，换来源或手动提供内容 |
| `API Error: Repeated 529 Overloaded errors` | Anthropic 的模型容量 | `/model` 换模型，或几分钟后再试 |
| `503 No available accounts` | 账号池型中转（如 sub2api） | 联系运营方；短时耗尽可稍后再试 |
| `503 No available channel for model … under group …` | new-api 类中转的分组与渠道 | 换该分组有的模型，或让运营方开通 |
| `503 … No available provider found` | Claude Code Hub 部署 | 管理后台检查供应商与熔断状态 |
| `503 no available server` | 网关前的负载均衡找不到健康后端 | 中转或自建网关的服务停了或在重启 |
| `503 no healthy upstream` | 某个反向代理没有可用上游 | 无 base URL 且状态页有故障时等待，否则找网关方 |

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

![先看 /status 有没有 Anthropic base URL，再按报错原文区分直连 Anthropic 与中转或网关返回的 403、503、529](https://blog.laozhang.ai/posts/zh/claude-code-403-503-529-errors/img/error-source-map.webp)

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

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

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

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

```bash
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 与代理错误排查](https://blog.laozhang.ai/zh/posts/claude-api-error-connection-error) 处理。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`：

```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 装的是同一个插件，处理方式相同。

![浏览器读系统代理，终端里的 claude 只读环境变量，从图标启动的 VS Code 拿不到 shell 变量，把 HTTPS_PROXY 写进 ~/.claude/settings.json 让两边一致](https://blog.laozhang.ai/posts/zh/claude-code-403-503-529-errors/img/proxy-env-paths.webp)

### 所在地区不在支持名单里

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

这种情况下该做的是停止在官方直连上反复尝试，换一条你所在地区可以使用的接入方式。可选的路线（云平台、中转、替代工具）和各自的取舍见 [Claude Code 国内使用指南：安装、注册、中转和稳定接入怎么选](https://blog.laozhang.ai/zh/posts/claude-code-china-access-guide)。

### 登录后出现 `Request not allowed`

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

1. Claude Pro / Max 用户：到 [claude.ai/settings](https://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](https://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](https://status.claude.com) 或末尾写的状态页，几分钟后再试。

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

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

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

```bash
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、模型和网关](https://blog.laozhang.ai/zh/posts/claude-code-api-configuration)。

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

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

- 地区不在支持列表里，却在走官方直连：换路线。
- 报错来自中转或网关（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 里用不了？先定位失败表面](https://blog.laozhang.ai/zh/posts/claude-not-working-in-vscode)。

## 需要换接入路线时

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

```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 文档](https://docs.laozhang.ai/api-reference/claude)，其他路线的比较见 [Claude Code 国内使用指南：安装、注册、中转和稳定接入怎么选](https://blog.laozhang.ai/zh/posts/claude-code-china-access-guide)。

## 常见问题

**报 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 不计入你的用量配额。经中转使用时怎么计费，以中转自己的说明为准。