Why does Claude Code return 401 Invalid token?

A 401 means the server did not recognise your key. Nine times out of ten the environment variable never took effect or the key was truncated when copied. Run echo $ANTHROPIC_AUTH_TOKEN to confirm the shell actually sees it, and check the key starts with sk-9c- with nothing cut off the end. Claude Code reads environment variables once at startup, so you must open a new terminal after changing them.

Why does Claude Code return 429 rate limit?

A 429 means you hit the concurrency ceiling. It is not a balance problem. Wait a few seconds and retry; it usually clears on its own. If it happens often, reduce how many tasks you run in parallel, and give batch scripts exponential backoff of 1s, 2s, 4s rather than hammering retries.

Why does Claude Code fail with a connection error?

Take Claude Code out of the picture first and curl the endpoint directly. If curl works, the problem is client configuration, usually a typo in ANTHROPIC_BASE_URL or a trailing slash or path. If curl also fails, it is your network or proxy.

Why do I get model not found?

Model ids are case and hyphen sensitive, so a hand-typed name with the wrong version suffix will not resolve. Call the /v1/models endpoint and copy the id straight from the response, or use the /model command inside Claude Code and pick from the list.

Why do I get context length exceeded?

The conversation has grown past the model context window. Run /clear to start fresh or /compact to condense the history. Longer term, let the tool read files on demand instead of loading an entire repository up front.

What should I include when reporting an error?

9Coding error responses carry a request id in the form (request id: 2026...). Send that id together with the timestamp, the model name and the full error text, and the exact call can be traced. A report that only says it does not work cannot be investigated.

Troubleshooting

Claude Code error troubleshooting

Find your error code, get one line on why it happens and one step to fix it. Almost every setup problem comes down to three things: the environment variable never took effect, the URL is wrong, or you hit the concurrency ceiling. Start with the table — most of these take thirty seconds.

Quick reference

What you see	Usually means	Do this first
`401` · `Invalid token`	Key not in effect or truncated	Full walkthrough →
`403`	Key disabled or out of scope	Full walkthrough →
`429` · rate limit	Concurrency ceiling, not balance	Full walkthrough →
Connection error	Wrong URL or blocked network	Full walkthrough →
SSL / certificate	Proxy intercepting TLS	Full walkthrough →
`model not found`	Wrong version or suffix in the id	Full walkthrough →
context length exceeded	Conversation grew too long	Full walkthrough →
Streaming cuts off midway	Proxy idle timeout	Raise the proxy read timeout
`529` · overloaded	Upstream model is saturated	Retry later or switch model
`x-bb-api-key` and other third-party errors	Returned by another service, not by 9Coding	Identify the source →

Connection and authentication

401 · Invalid token#

Symptom

The request is rejected outright, with a body like {"error":{"code":"","message":"Invalid token (request id: 2026...)","type":"new_api_error"}}.

Cause

The server did not recognise the key. Nine times out of ten the key itself is fine — either the environment variable never took effect or the value was truncated when copied.

Fix

First confirm the shell actually sees them:

terminal

echo $ANTHROPIC_BASE_URL
echo $ANTHROPIC_AUTH_TOKEN

Empty output means the variables never reached this shell, or you did not restart the terminal after adding them. Claude Code reads environment variables once at startup — open a new terminal (or source ~/.zshrc) after any change.

Output looks right but still 401? Check the key begins with sk-9c- and nothing is missing from the end. Recopying it from the console is the safest move.

403 · Forbidden#

Symptom: The key is recognised, but this particular call is not allowed.
Cause: The key has been disabled or deleted, or its scope is restricted.
Fix: Open the key management page in the console and confirm the key still exists and is active. Deleting it and creating a fresh one is the fastest way to rule this out — new keys work immediately, with no propagation delay.

Connection error#

Symptom

The request fails before reaching the server: connection error, ECONNREFUSED, or a timeout.

Cause

Either the URL is wrong or traffic cannot leave your machine. Take Claude Code out of the picture first — one curl separates the two cases.

Fix

terminal

curl -s https://api.9coding.com/v1/models \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"

curl works (returns a model list or a JSON error) → the network is fine and it is client configuration. Check ANTHROPIC_BASE_URL for typos, a trailing /, or an extra /v1. The correct value is exactly https://api.9coding.com — the client appends the path itself.

curl also fails → network or proxy. Check whether your proxy only applies to the browser, whether corporate policy blocks the host, and run curl -v to see which step stalls.

SSL / certificate errors#

Symptom: Certificate verification failures, unable to get local issuer certificate, or handshake timeouts.
Cause: Something in the middle — a proxy or security agent — is terminating TLS, and its root certificate is not trusted by your system.
Fix: Install that proxy's root certificate into the system trust store, or turn the proxy off briefly to confirm it is the cause. Do not work around this by disabling certificate verification — that hands your traffic to whoever is in the middle.

Rate limits and timeouts

429 · rate limit#

Symptom

Requests are throttled with a rate limit or too many requests message.

Cause

You hit the concurrency ceiling — this is not a balance problem. The two are worded differently; insufficient balance says so explicitly.

Fix

Wait a few seconds and retry; it normally clears itself. Hitting it repeatedly means too much runs in parallel — bring the number of concurrent tasks down.

Always give batch scripts exponential backoff: 1s, 2s, 4s, rather than retrying flat out. Aggressive retries only keep the limit engaged for longer.

529 · overloaded#

Symptom: A 529 response, or a message saying the model is overloaded.
Cause: The upstream model is under heavy load. Nothing to do with your configuration; popular models see this at peak hours.
Fix: Retry shortly, or switch to a comparable model to keep working. Use /model inside Claude Code — your session is preserved.
More: If it died mid-answer with no retry at all, that is the other arrival path and the standard retry mechanisms do not cover it — see 529 overloaded in depth.

Streaming responses cut off midway#

Symptom: Output stops partway through with no error, or the connection is reported as reset.
Cause: A streamed response is one long-lived connection, and an idle timeout anywhere along the path will cut it. Corporate proxies and some VPNs are the usual culprits.
Fix: Raise the proxy read timeout — long answers easily exceed 60 seconds — or bypass the proxy to confirm. A quick test: ask for a short answer. If short answers complete and long ones always break, it is a timeout.

Models and parameters

model not found#

Symptom

The model is reported as missing or unavailable.

Cause

A hand-typed id with the wrong version or an extra suffix. Model ids are case and hyphen sensitive — one character off and it will not resolve.

Fix

Ask the server what is currently available and copy the id verbatim:

terminal

curl -s https://api.9coding.com/v1/models \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"

Inside Claude Code, use /model and pick from the list — more reliable than typing it.

context length exceeded#

Symptom

An error saying the context limit or token count has been exceeded.

Cause

The conversation has outgrown the model context window. Most common in long sessions or after loading a large file in one go.

Fix

/clear for a fresh session, or /compact to condense the history and carry on.

The durable fix is not to load an entire repository up front — letting the tool read files on demand is both cheaper and more accurate.

None of the above? Work through this order

When you hit something unfamiliar, do not start by guessing. This order narrows it to one place within a few minutes:

Check the environment: echo $ANTHROPIC_BASE_URL $ANTHROPIC_AUTH_TOKEN. Empty means it never took effect — restart the terminal.
Bypass the client: run the curl above. Success means client configuration; failure means network.
Try another model: one bad model and a broken channel need completely different fixes.
Minimal repro: open an empty session and ask something trivial. Errors inside complex sessions are often about context, not access.
Still stuck? Send it to us — with the details below.

Include these four things: ① the full error text, especially the request id inside it (request id: 2026... — it points straight at that one call); ② when it happened; ③ the model name; ④ the result of the curl in step 2. With those four it is usually a single-pass diagnosis; "it doesn't work" cannot be investigated.

Claude Code setup — two environment variables, three minutes
Cursor　·　OpenAI SDK　·　Gemini
FAQ — billing, model coverage, accounts

Start free Setup guide

Claude Code error troubleshooting

Quick reference

Connection and authentication

401 · Invalid token#

403 · Forbidden#

Connection error#

SSL / certificate errors#

Rate limits and timeouts

429 · rate limit#

529 · overloaded#

Streaming responses cut off midway#

Models and parameters

model not found#

context length exceeded#

None of the above? Work through this order

Related