Claude Code 报错速查
Claude Code 的 API Error 后面是状态码和服务器的原话。下表按状态码列出请求发到 RelaySwitch 网关时每一种报错的错误码、原因和处理办法，都取自网关的实际行为。
01先读懂一条报错
Claude Code 的报错长这样：API Error: 402 … (insufficient_balance)。三样东西有用：状态码（402）、括号里的错误码、请求 id。状态码告诉你方向，错误码告诉你具体是哪一条规则，请求 id 用来查那一次调用。
本页的表只适用于请求发到本站的情况。先在会话里运行 /status，确认 Anthropic base URL 一行是 https://api.relayswitch.io/v1。没有这一行，请求走的是官方接口，报错含义以 Claude Code 官方的报错参考 为准。
02按状态码查
| 状态与错误码 | 含义 | 处理 |
|---|---|---|
400invalid_request | 请求本身有问题：正文不是 JSON 对象、没写 model、同时带了两个不同的密钥，或者把密钥写在了 URL 里。 | 最常见的是 ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_API_KEY 同时设置且值不同，删掉一个。 |
400upstream_invalid_request | 请求格式没问题，但模型不接受其中的参数。 | 报文里有具体原因。多见于换了模型之后，旧会话里的思考参数或工具定义新模型不认，开一个新会话。 |
401invalid_api_key | 没带密钥、密钥不对，或者密钥已被吊销。报文分别是 No API key was sent、The API key is not valid、The API key has been revoked。 | 核对密钥有没有复制完整（以 sk-relay- 开头）；在 /status 里确认 Auth token 一行存在。 |
402insufficient_balance | 预付余额不够支付这次请求。 | 充值后立即恢复，不用改任何配置。 |
402key_budget_exhausted、daily / weekly / monthly_limit_reached | 账户还有余额，但这把密钥自己的预算或周期消费上限用完了。 | 在控制台调高这把密钥的预算或上限，或者等下一个周期（UTC 日、周一、自然月）。 |
402spend_cap_reached | 新账户在第一笔付款结算完成之前，累计消费有一个上限。 | 报文里写了上限金额；付款结算后解除。 |
403scope_denied、ip_not_allowed、admin_key、account_frozen | 密钥有效，但密钥上的限制不允许这次请求。 | Claude Code 报错 403 |
404model_not_found | 模型 id 不在目录里。报文是 No such model: <id>。 | id 要和模型页上的完全一致，不是显示名；用下面的 curl 列出密钥能调用的全部 id。 |
413invalid_request | 请求正文超过 10 MB。 | 多半是贴进了大图或大文件，压缩后再发。 |
429rate_limited | 这把密钥的每分钟请求数、每分钟 tokens 或并发数到了上限。 | 响应头 retry-after 给出等待秒数。默认每把密钥每分钟 600 次请求，可以在密钥上改；新账户头 24 小时按每分钟 60 次计。 |
429upstream_rate_limited | 这个模型的线路此刻繁忙，而且没有别的线路可换。 | 稍后重试，或者用 /model 换一个模型。 |
429session_cap、loop_detected | 密钥上设了会话上限；或者密钥开了循环保护，同一个会话在 10 分钟内把同一个工具调用或同一个请求发了 5 次以上。 | 报文里有恢复时间。loop_detected 通常说明代理卡在了重复动作里，先看它在做什么。 |
502upstream_error | 模型的线路出错，或者回答中途断了，没有任何内容返回给你。 | 带 retry-after，等这么久再试。Claude Code 会自己重试。 |
503upstream_unavailable | 这个模型此刻没有线路在应答。Anthropic 格式下错误类型是 overloaded_error。 | retry-after 为 30 秒。持续出现时看状态页，或者换模型。 |
以上各项都不扣费：请求要么没有到达模型，要么没有内容返回。
500 很少见，报文是 internal_error，直接重试即可。表里没有的 4xx 报文，把请求 id 发给我们。
03529 和过载
04Claude Code 自己会重试什么
按 Claude Code 的报错参考（读取于 2026-11-11）：暂时性的失败它最多自动重试 10 次，间隔逐次拉长，全部失败才把报错显示出来。会重试的有服务器错误、过载、还没开始输出就超时、连接中断，以及临时性的 429。401 和 403 不重试，网关因为消费上限返回的 429 也不重试。
所以 5 开头的报错一闪而过可以不管；反复出现的 4 开头报错，重试没有意义，要改配置。
05没有状态码的报错
Unable to connect to API、Connection refused、Request timed out 这一类没有状态码，说明请求没有得到任何服务器的回答，问题在本机到服务器之间。用下面的命令在同一个终端里直接测：
# 1. 密钥能调用哪些模型（401 = 密钥问题，200 = 密钥没问题）curl -i https://api.relayswitch.io/v1/models \ -H "Authorization: Bearer sk-relay-..." # 2. 按 Claude Code 的格式发一条最小请求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"}]}'curl 能通而 Claude Code 不通，是变量没有传进 Claude Code 的进程；curl 也不通，是本机的网络、代理或 DNS 的问题，这部分本站无法代为解决。响应慢导致的超时，可以把环境变量 API_TIMEOUT_MS 调大。
常见问题
- Claude Code 报错 API Error 怎么解决？
- API Error 后面跟着状态码和服务器的原话。先看状态码定方向：4 开头是这次请求或这把密钥的问题，改了才会好；5 开头和大部分 429 是暂时的，Claude Code 会自己重试。再看报文末尾括号里的错误码，对照本页的表。
- 报错的请求会扣费吗？
- 不会。401、402、403、404 在请求到达模型之前就返回了；429、502、503 没有内容返回给你，同样不扣费。只有成功返回的请求按实际 tokens 计费，每一条都有回执。
- Claude Code 报 529 Overloaded 是中转站的问题吗？
- 529 是 Anthropic 官方接口表示过载的状态码。本站网关自己不返回 529：某条线路过载时请求会自动换到同一模型的下一条线路，全部线路都不应答时返回 503。所以在本站密钥上看到的过载是 503 upstream_unavailable。
- Claude Code 报 400 怎么办？
- 看报文。提到 more than one API key，是两个密钥变量同时设了；提到 names no model 或 not a JSON object，是请求被别的工具改坏了；其他情况多半是模型不接受某个参数，开一个新会话或换回原来的模型。
- 一直转圈没有报错，是怎么回事？
- 多半是 Claude Code 正在重试。按它的文档，暂时性的失败最多重试 10 次，间隔逐次拉长，全部失败后才显示报错。等它结束，或者按 Esc 中断后用 curl 直接测一次。
- 找客服时要提供什么？
- 请求 id。本站每个响应（包括报错）的响应头里都有 x-uplink-request-id，Anthropic 格式的报错正文里也有 request_id。发到 hello@relayswitch.io，我们按 id 查到那一次调用。
失败的请求不扣费
429、502、503 不计费并带 retry-after；一条线路出错时自动换下一条。