Claude Code / Codex 常见报错怎么解决
看报错先看两样东西：HTTP 状态码，和 JSON 里 error.message 的那句话。下面按类别列出 CCSub 用户最常遇到的报错——选题来自真实请求日志里出现次数最多的错误，以及 Claude Code、Codex 客户端自己显示的连接类报错。
鉴权（401）
Key 没带上、带错了，或者被禁用
- 401Claude CodeCC Switch
API Error: 401 {"type":"error","error":{"type":"authentication_error","message":"Invalid or disabled API key"}}Key 没带上或带错了。用 /status 看 Claude Code 实际用的是哪个变量，到 /keys 重新复制完整 Key，删掉多余的 ANTHROPIC_API_KEY 后重开终端。
查看解法 - 401Codex CLICC Switch
unexpected status 401 Unauthorized: {"type":"error","error":{"type":"authentication_error","message":"Missing or invalid API key"}}, url: https://www.ccsub.net/api/v1/responses看报错里的 url 判断请求发去了哪；用自定义 provider + env_key 指定 CCSub 的 Key，并在启动 Codex 的同一个环境里设置好这个变量。
查看解法
余额与额度（402）
按量余额不够，或月卡当日额度已用完
限流（429）
每分钟请求数或同时进行的请求数超了
请求本身的问题（400 / 404）
型号名写错、地址写错、请求体太大
- 404Claude CodeCodex CLICursor
There's an issue with the selected model (claude-opus-6). It may not exist or you may not have access to it. Run /model to pick a different model.model 标识写错了，按 /api/v1/models 列表里的 id 改（用短横线）；如果所有型号都 404、返回的是一整页 HTML，就是 Base URL 写错了。
查看解法 - 400Claude CodeopencodeCodex CLI
API Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"Invalid JSON in request body: Unterminated string in JSON at position 10407567 (line 1 column 10407568)"}}position 是上千万的数字 = 请求体太大、传输途中被截断：/compact 或 /clear、别反复贴大截图、大文件分段读。position 很小 = 发出去的 JSON 本身格式不对。
查看解法
上游繁忙与超时（503 / 504）
暂时性问题，大多重试即可
- 503Claude CodeCodex CLICursor
API Error: 503 {"type":"error","error":{"type":"overloaded_error","message":"上游线路暂时不可用，请稍后重试（不是您账户余额的问题） | Upstream temporarily unavailable, please retry shortly (this is not about your account balance)."}}CCSub 已自动换线重试过，这次仍没有可用线路。等一两分钟在原会话里发「继续」，或用 /model 换个型号；不扣费，也不是你的余额问题。
查看解法 - 504Claude CodeCodex CLICline
API Error: 504 {"type":"error","error":{"type":"timeout_error","message":"Upstream timed out"}}等上游的时间超过上限了。自己调用时改成流式（stream: true），上下文太长就 /compact，长输出拆成几次；偶发一次直接重试即可，不计费。
查看解法
本地网络与连接
请求没到 CCSub，或流式连接中途断开
- 客户端报错Claude CodeCC Switch
Unable to connect to API (ECONNREFUSED)请求没到 CCSub，多半是本地代理变量指向了没开的代理。env | grep -i proxy 查一下，unset 掉或给 ccsub.net 加 NO_PROXY；首次启动卡在连不上 api.anthropic.com 则改 ~/.claude.json。
查看解法 - 客户端报错Codex CLICC Switch
stream disconnected before completion: stream closed before response.completed流在结束前断了。确认 base_url 是 https://www.ccsub.net/api/v1，去掉干扰终端的代理，过长的单轮任务调低推理强度或拆小，并在 provider 里调大 stream_max_retries。
查看解法
按工具找
Claude Code
- 401 · Claude Code 报 401 Invalid API Key 怎么解决
- 402 · 报 402 insufficient_balance「余额不足」怎么解决
- 429 · 报 429 rate limit exceeded / concurrency limit exceeded 怎么解决
- 404 · Claude Code 报 There's an issue with the selected model（404 模型不存在）怎么解决
- 400 · 报 400 Invalid JSON in request body: Unterminated string（请求体过大）怎么解决
- 503 · 报 503 overloaded_error「上游线路暂时不可用」怎么解决
- 504 · 报 504 timeout_error「Upstream timed out」怎么解决
- Claude Code 报 API Error: Connection error（Unable to connect to API）怎么解决
Codex CLI
- 401 · Codex 报 unexpected status 401 Unauthorized 怎么解决
- 402 · 报 402 insufficient_balance「余额不足」怎么解决
- 429 · 报 429 rate limit exceeded / concurrency limit exceeded 怎么解决
- 404 · Claude Code 报 There's an issue with the selected model（404 模型不存在）怎么解决
- 400 · 报 400 Invalid JSON in request body: Unterminated string（请求体过大）怎么解决
- 503 · 报 503 overloaded_error「上游线路暂时不可用」怎么解决
- 504 · 报 504 timeout_error「Upstream timed out」怎么解决
- Codex 报 stream disconnected before completion 怎么解决
Cursor
Cline
Cherry Studio
CC Switch
opencode
SDK / curl 直接调用
- 402 · 报 402 insufficient_balance「余额不足」怎么解决
- 429 · 报 429 rate limit exceeded / concurrency limit exceeded 怎么解决
- 404 · Claude Code 报 There's an issue with the selected model（404 模型不存在）怎么解决
- 400 · 报 400 Invalid JSON in request body: Unterminated string（请求体过大）怎么解决
- 503 · 报 503 overloaded_error「上游线路暂时不可用」怎么解决
- 504 · 报 504 timeout_error「Upstream timed out」怎么解决
还没有 CCSub 账号？
注册后在控制台创建 API Key，填进 Claude Code、Codex 等工具即可使用，按实际用量计费。
