Fix "402 insufficient_balance" (余额不足) errors

Other forms of the same error

• 余额不足（可用 $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

The message is in Chinese — here's what it says

CCSub returns all three variants with error.type set to insufficient_balance. The message text is Chinese, so here's the translation and what each one means.

1. 余额不足，请前往 … 充值 — "Insufficient balance, please top up." You have no active subscription and your available balance is zero or below. The fix is to add pay-as-you-go balance on the purchase page.

2. 余额不足（可用 $x，本次预估 $y）— "Insufficient balance (available $x, this request estimated at $y)." This is the confusing one, because your balance isn't zero.

It's caused by holds. Before forwarding each request, CCSub places a hold for an estimated cost based on the model. When the request completes, it charges the actual token usage and releases the difference. The current estimates in the code are roughly $0.50 per request for Opus-tier models, $0.15 for Sonnet-tier and $0.03 for Haiku-tier, multiplied by the pricing multiplier of the key's group. In practice:

• With $0.30 left, an Opus-tier request is refused because the $0.50 hold can't be placed, even if it would only have cost a few cents. Use a cheaper model or top up.
• Every in-flight request holds its own amount. If Claude Code is running several subagents in parallel, their holds can eat your available balance and the next request gets a 402. Once earlier requests finish and release their holds, you're fine again.
• An interrupted request can occasionally leave a stale hold. The system clears those every five minutes, so if you know you have enough balance, wait a few minutes and retry.

3. 今日月卡额度（$N/天）已用完 — "Today's subscription quota ($N/day) is used up; it resets at 00:00 Beijing time." Subscriptions come with a fixed USD amount per day. It resets at midnight Beijing time (UTC+8), and whatever you don't use that day is gone — it doesn't carry over. Requests use today's quota first and then fall back to your pay-as-you-go balance automatically, so this message means both are empty. Wait for the reset or add some balance. The subscriptions page shows how much of today's quota is left.

Is it really my account?

CCSub's own 402 always has a Chinese message with a link to https://www.ccsub.net/purchase. If you see English text such as Insufficient Balance or insufficient account balance, it's not about you. When an upstream line has a billing problem, CCSub rewrites it as a 503 that says the upstream is temporarily unavailable and explicitly not about your account balance. See 503 upstream overloaded.

How it shows up in different tools

• Claude Code: API Error: 402 {...}. It isn't retried automatically; after topping up, type "continue" in the same session.
• Codex CLI: unexpected status 402 Payment Required: {...}, url: https://www.ccsub.net/api/v1/responses.
• Cursor, Cline, Cherry Studio and similar: usually print the message as-is in the chat panel.
• Your own code: HTTP 402 with error.type = insufficient_balance. Surface a "top up" prompt instead of retrying in a loop.

Blocked requests are listed in your usage log at $0, so nothing was deducted.

FAQ

Related errors

• API Error: 429 {"type":"error","error":{"type":"rate_limit_error","message":"API Key request rate exceeded"}}Request-rate errors: raise the key's requests-per-minute or split traffic across keys. Concurrency errors: run fewer sessions or subagents at once — the limit is per account, so extra keys don't help.
• API Error: 503 {"type":"error","error":{"type":"overloaded_error","message":"上游线路暂时不可用，请稍后重试（不是您账户余额的问题） | Upstream temporarily unavailable, please retry shortly (this is not about your account balance)."}}CCSub already failed over between lines and none was free at that moment. Wait a minute and type "continue", or switch models with /model. Not billed, and not about your balance.
• API Error: 401 {"type":"error","error":{"type":"authentication_error","message":"Invalid or disabled API key"}}The key never arrived or it's the wrong one. Check /status, re-copy the full key from the dashboard, and unset any leftover ANTHROPIC_API_KEY.