Teapot Router / Documentation
Claude Code troubleshooting: connection, 401, and quota errors
Match the error to the fix: network and proxy, key and base URL, balance and quota — three checks for three failure classes.
Open workspaceConnection or timeout: check the network path first
- The CLI doesn't inherit your system proxy. Run `echo $https_proxy` — if it's empty, export it and retry.
- The VSCode extension has its own network stack and may not inherit system proxy or env vars — configure the proxy inside the extension.
- On custom endpoints, verify ANTHROPIC_BASE_URL for stray characters or slashes; don't mix the official URL and a gateway URL.
If it works on another network (phone hotspot) but not yours, it's purely network — not your key.
401 or 403: check key and address
- 401 usually means the key: incomplete copy (leading/trailing spaces), revoked or expired, or a key from a different provider.
- With custom endpoints, key and address must match as a pair — one provider's key against another's URL will always 401.
- A typo'd field name in settings.json env can silently fall back to the default endpoint: it looks configured but still hits the official URL.
Revoked keys never come back. Restart the client after switching keys.
429, quota, and model not found
- 429 is rate limiting: wait for the window or lower concurrency; persistent 429 means the model has rate limits.
- 'Insufficient quota' has two layers: account balance, and this key's separate limit — the key limit caps usage, it is not extra credit.
- 'Model not found': match the model ID in your client exactly (case, version) against the Models catalog.
Every request's model/tokens/cost is in Usage — after fixing the error, reconcile one entry to make sure silent retries didn't double-bill you.