报 402 insufficient_balance「余额不足」怎么解决

同一个问题的其他写法

• 余额不足（可用 $0.12，本次预估 $0.50），请前往 https://www.ccsub.net/purchase 充值
• 今日月卡额度（$50/天）已用完，将于北京时间 0 点重置；如需继续使用，请前往 https://www.ccsub.net/purchase 充值余额
• unexpected status 402 Payment Required: {"type":"error","error":{"type":"insufficient_balance","message":"余额不足，请前往 https://www.ccsub.net/purchase 充值"}}, url: https://www.ccsub.net/api/v1/responses

三种 402 文案分别是什么意思

CCSub 的 402 错误类型都是 insufficient_balance，但 message 有三种，原因和处理方式不一样。

1. 余额不足，请前往充值

账户没有有效月卡，并且可用余额已经小于等于 0。这种情况只能去 充值页 充值按量余额。按量余额不会因为月份结束而清零。

2. 余额不足（可用 $x，本次预估 $y）

这一种最容易让人困惑：明明余额不是 0，为什么还拦？

原因是预冻结。每个请求转发前，CCSub 会按型号先冻结一笔估算费用，请求结束后按实际 Token 用量结算，多冻的部分释放回来。代码里目前的估算值大约是：Opus 档每次 $0.50，Sonnet 档 $0.15，Haiku 档 $0.03，再乘以这把 Key 所在分组的倍率。所以：

• 余额只剩 $0.30 时请求 Opus 档型号，会因为不够冻结 $0.50 被拦，哪怕这次实际只会花几分钱。换成便宜的型号，或者充值后再用。
• 同时开很多个请求时，每个都会冻结一笔。例如 Claude Code 同时跑多个子代理，可用余额会被这些冻结占满，后发的请求就会 402。等前面的请求结束、冻结释放后就恢复了。
• 请求异常中断时偶尔会残留冻结，系统每 5 分钟自动清理一次。余额明明够、只是短时间报这个错，等几分钟重试即可。

3. 今日月卡额度（$N/天）已用完

月卡每天有固定的美元额度，按北京时间 0 点重置，当天用不完的部分作废、不会累积到第二天。计费顺序是先用当天额度，额度用完自动改用按量余额，所以只有「当天额度用完」并且「按量余额也没有」时才会看到这句。可以等北京时间 0 点重置，或者充值一点按量余额接着用。月卡页面 会显示「剩余今日额度」。

怎么确认不是上游的问题

CCSub 自己返回的 402 一定是中文文案、带 https://www.ccsub.net/purchase 链接。如果你看到的是英文的 Insufficient Balance、insufficient account balance 之类，那不是你的账户：上游线路账户的余额问题会被 CCSub 改写成 503，文案是「上游线路暂时不可用，请稍后重试（不是您账户余额的问题）」，处理方法见 503 上游繁忙。

不同工具里长什么样

• Claude Code：API Error: 402 {...}，不会自动重试，充值后在原会话里发一句「继续」即可。
• Codex CLI：unexpected status 402 Payment Required: {...}, url: https://www.ccsub.net/api/v1/responses。
• Cursor、Cline、Cherry Studio 等：通常把 message 原样显示在对话框里。
• 自己写代码：HTTP 状态码 402，JSON 里 error.type 是 insufficient_balance，可以据此提示用户去充值，不要无限重试。

被 402 拦下的请求会以 $0 的费用出现在 使用记录 里，不会扣钱。

常见问题

相关报错

• API Error: 429 {"type":"error","error":{"type":"rate_limit_error","message":"API Key request rate exceeded"}}每分钟请求数超了就在 Keys 页面调高这把 Key 的速率或分开用多把 Key；并发超了就减少同时跑的会话和子代理——并发按账号计算，多建 Key 没用。
• 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 换个型号；不扣费，也不是你的余额问题。
• API Error: 401 {"type":"error","error":{"type":"authentication_error","message":"Invalid or disabled API key"}}Key 没带上或带错了。用 /status 看 Claude Code 实际用的是哪个变量，到 /keys 重新复制完整 Key，删掉多余的 ANTHROPIC_API_KEY 后重开终端。