Fix common Claude Code & Codex API errors
When an error shows up, look at two things: the HTTP status code and the error.message string in the JSON body. The pages below are grouped by type. They cover the errors CCSub users hit most often in real request logs, plus the connection errors that Claude Code and Codex CLI print on their own.
Authentication (401)
The key is missing, wrong, or disabled
- 401Claude CodeCC Switch
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.
See the fix - 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/responsesCheck the url in the error to see where the request went, then define a custom provider with env_key and set that variable in the same environment Codex runs in.
See the fix
Balance & quota (402)
Out of balance, or today's subscription quota is used up
Rate limits (429)
Too many requests per minute, or too many at once
Bad requests (400 / 404)
Wrong model ID, wrong URL, or an oversized request
- 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.The model ID is wrong — use an id from /api/v1/models (hyphenated). If every model fails and the response is an HTML page, your base URL is wrong instead.
See the fix - 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)"}}A position in the millions means the body was truncated in transit: /compact or /clear, stop re-pasting big screenshots, read large files in chunks. A tiny position means the JSON itself is malformed.
See the fix
Busy or slow upstream (503 / 504)
Usually temporary — a retry often fixes it
- 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 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.
See the fix - 504Claude CodeCodex CLICline
API Error: 504 {"type":"error","error":{"type":"timeout_error","message":"Upstream timed out"}}The upstream took too long to start answering. Use streaming (stream: true) in your own code, /compact very long contexts, and split long outputs. A one-off 504 just needs a retry and isn't billed.
See the fix
Local network & connection
The request never reached CCSub, or the stream dropped
- Client-sideClaude CodeCC Switch
Unable to connect to API (ECONNREFUSED)The request never reached CCSub — usually a proxy variable pointing at a proxy that's off. Check env | grep -i proxy, unset it or add NO_PROXY for ccsub.net. Stuck on first launch? Edit ~/.claude.json.
See the fix - Client-sideCodex CLICC Switch
stream disconnected before completion: stream closed before response.completedThe stream dropped before it finished. Make sure base_url is https://www.ccsub.net/api/v1, take local proxies out of the path, shorten very long turns, and raise stream_max_retries on the provider.
See the fix
Browse by tool
Claude Code
- 401 · Fix Claude Code "API Error: 401 Invalid or disabled API key"
- 402 · Fix "402 insufficient_balance" (余额不足) errors
- 429 · Fix 429 "rate limit exceeded" and "concurrency limit exceeded"
- 404 · Fix "There's an issue with the selected model" (404 model not found) in Claude Code
- 400 · Fix "400 Invalid JSON in request body: Unterminated string in JSON" (request too large)
- 503 · Fix "API Error: 503 overloaded_error" and "Repeated 529 Overloaded errors"
- 504 · Fix "504 timeout_error: Upstream timed out"
- Fix Claude Code "API Error: Connection error" (Unable to connect to API)
Codex CLI
- 401 · Fix Codex "unexpected status 401 Unauthorized"
- 402 · Fix "402 insufficient_balance" (余额不足) errors
- 429 · Fix 429 "rate limit exceeded" and "concurrency limit exceeded"
- 404 · Fix "There's an issue with the selected model" (404 model not found) in Claude Code
- 400 · Fix "400 Invalid JSON in request body: Unterminated string in JSON" (request too large)
- 503 · Fix "API Error: 503 overloaded_error" and "Repeated 529 Overloaded errors"
- 504 · Fix "504 timeout_error: Upstream timed out"
- Fix Codex "stream disconnected before completion"
Cursor
Cline
- 402 · Fix "402 insufficient_balance" (余额不足) errors
- 429 · Fix 429 "rate limit exceeded" and "concurrency limit exceeded"
- 404 · Fix "There's an issue with the selected model" (404 model not found) in Claude Code
- 503 · Fix "API Error: 503 overloaded_error" and "Repeated 529 Overloaded errors"
- 504 · Fix "504 timeout_error: Upstream timed out"
Cherry Studio
CC Switch
opencode
SDK / curl
- 402 · Fix "402 insufficient_balance" (余额不足) errors
- 429 · Fix 429 "rate limit exceeded" and "concurrency limit exceeded"
- 404 · Fix "There's an issue with the selected model" (404 model not found) in Claude Code
- 400 · Fix "400 Invalid JSON in request body: Unterminated string in JSON" (request too large)
- 503 · Fix "API Error: 503 overloaded_error" and "Repeated 529 Overloaded errors"
- 504 · Fix "504 timeout_error: Upstream timed out"
New to CCSub?
Sign up, create an API key in the dashboard, and paste it into Claude Code, Codex CLI or your editor. You pay for what you use.