Claude Code 报错 403
403 的意思是“认得你，但不让你做这件事”。先弄清是谁返回的：Anthropic 官方接口，还是你配置的网关。两边的报文不同，处理办法也不同。
01第一步：是谁返回的
Claude Code 把服务器的回答原样打印在 API Error: 403 后面，所以这段文字是谁写的，问题就出在谁那里。在会话里运行 /status：
- 有
Anthropic base URL一行：请求发往那个地址，403 是那个网关返回的。地址是 https://api.relayswitch.io/v1 的话，往下看“本站网关的五种 403”。 - 没有这一行：请求发往 Anthropic 官方接口，看下一节。
本站网关的每个错误都带两个响应头：x-uplink-error 是错误码，x-uplink-request-id 是请求 id。报文正文是 Anthropic 的错误格式，错误码写在 message 末尾的括号里：
HTTP/2 403x-uplink-error: scope_deniedx-uplink-request-id: ul_... { "type": "error", "error": { "type": "permission_error", "message": "This key may not call claude-opus-5-5. (scope_denied)" }, "request_id": "ul_..."}02官方接口的 Request not allowed
API Error: 403 Request not allowed 不是本站网关的报文，网关的代码里没有这句话。它出现在用 claude.ai 账号或 Anthropic Console 密钥的会话里。Claude Code 的 官方排错页（读取于 2026-11-11）在“登录后 403”一节列了三项检查：
- 订阅用户：到 claude.ai 的设置页确认订阅还在有效期内。
- Console 用户：确认账号有 Claude Code 或 Developer 角色，由管理员在成员页分配。
- 公司网络：代理可能改动了 API 请求，按官方的网络配置页检查代理设置。
这三项都属于 Anthropic 账号和你本机的网络，本站帮不上忙，也无法替你判断。账号本身被暂停时报文是另一种，见 Claude Code 封号。
03本站网关的五种 403
请求发到 https://api.relayswitch.io/v1 时，403 只有下面五种，都发生在请求到达模型之前，不扣费：
| 错误码与报文 | 原因 | 处理 |
|---|---|---|
scope_deniedThis key may not call <模型 id>. | 这把密钥设了模型白名单，请求的 id 不在名单里。 | 在控制台把这个 id 加进密钥的白名单，或者换一把没有白名单的密钥。Claude Code 的后台任务会用 haiku 别名对应的模型，白名单里别漏了它。 |
ip_not_allowedThis API key may not be used from this IP address. | 这把密钥设了 IP 白名单，请求来自名单之外的地址。 | 在控制台改密钥的 IP 白名单；出口地址不固定的环境不要设这一项。 |
admin_keyThis is an admin key: it manages keys through /v1/keys and cannot call models. | 填进去的是管理密钥。管理密钥只用来创建和管理密钥，不能调用模型。 | 在控制台另建一把普通 API 密钥，填进 ANTHROPIC_AUTH_TOKEN。 |
account_frozenThis account is on hold. Contact support. | 账户被暂停。 | 发邮件到 hello@relayswitch.io，附上请求 id。 |
credential_required<模型 id> runs on your own … key, which cannot be stored yet. | 这个模型要用你自己在开发商那里的密钥，本站暂时不托管。 | 换一个目录里列出的模型 id。 |
最常见的是前两种：给密钥设了白名单，过后忘了。新建的密钥默认没有任何白名单，能从任何地址调用目录里的全部模型。
04白名单怎么设才不误伤
模型白名单和 IP 白名单是为了限制一把密钥泄露之后的损失，本身是好习惯。Claude Code 用的密钥设白名单时注意三点：
- 把三个别名对应的 id 都放进去。主对话用 opus 或 sonnet，后台功能用 haiku 别名指向的模型，漏掉 haiku 会让一部分请求报 403，而主对话看起来一切正常。
- 白名单里写的是模型 id，不是显示名，要和模型页上的 id 完全一致。
- IP 白名单只适合出口地址固定的机器，比如一台服务器。笔记本换个网络，出口地址就变了。
改完白名单不用换密钥，也不用重启 Claude Code，一分钟左右按新的名单判定。
05用 curl 复现
绕开 Claude Code，用同一把密钥直接发一条请求。-i 会打印响应头，错误码和请求 id 都在里面：
curl -i https://api.relayswitch.io/v1/messages \ -H "Authorization: Bearer sk-relay-..." \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{"model": "claude-haiku-5-5", "max_tokens": 16, "messages": [{"role": "user", "content": "回复 ok"}]}'返回 200，说明密钥和地址都没问题，403 出在 Claude Code 请求的那个模型上：把 model 换成报文里的 id 再试，多半是 scope_denied。在另一台机器上能通、这台不通，是 ip_not_allowed。
06容易和 403 混淆的状态码
- 401：密钥无效、被吊销，或者根本没发出去。先查变量有没有传进进程。
- 402：余额不足，或者密钥的预算、消费上限用完了。充值或调高上限后立即恢复。
- 429：速率限制，和权限无关。等响应头 retry-after 给出的秒数再发。
- 404：模型 id 不在目录里，多半是拼写（
claude-opus-5-5写成了claude-opus-5.5之类）。
每个状态码的完整说明在 Claude Code 报错速查。
常见问题
- Claude Code 报 403 Request not allowed 是什么意思？
- 这句报文来自 Anthropic 官方接口，不是本站网关发的。Claude Code 的官方排错页给出的三个检查方向是：Pro、Max 这类订阅是否在有效期内；Console 账号有没有 Claude Code 或 Developer 角色；公司代理有没有改动请求。本站网关的 403 报文不同，每一条末尾都带括号里的错误码。
- 403 之后重新登录或者重试有用吗？
- 没用。403 是权限判定，不是临时故障：同一把密钥、同一个模型、同一个地址再发一次，结果一样。按 Claude Code 的文档，它也不会自动重试 403。要改的是报文里指出的那一项。
- 怎么确认请求到底发到了哪里？
- 在 Claude Code 里运行 /status。Status 页有 Anthropic base URL 一行，说明请求发往那个地址；没有这一行，请求发往 Anthropic 官方接口，这时看到的 403 与任何中转站无关。
- 密钥是对的，为什么还是 403？
- 403 说明密钥本身有效（无效密钥是 401），是密钥上的限制拦住了这次请求：模型白名单、IP 白名单，或者这是一把管理密钥。看响应头 x-uplink-error，或者报文末尾括号里的错误码，就知道是哪一种。
- 403 会扣费吗？
- 不会。请求在到达模型之前就被拒绝了，没有产生任何 tokens。
密钥的限制，都在你自己手里
模型白名单、IP 白名单、预算和速率都按密钥设置，报错里写明是哪一项。