LLM API error codes, explained and fixed
Every error your client throws maps to an HTTP status code, and each code points at a different layer: your key, your balance, your request rate, or the upstream model. This page is the quick reference for Router One's OpenAI-compatible API and the CLI tools that sit on top of it. Start with the final request row in Dashboard → Logs; if a provider retry needs deeper investigation, keep the request_id so support can correlate intermediate attempts in operational logs.
Quick reference
The first thing to check for each status code:
| Code | Meaning | First thing to check |
|---|---|---|
| 401 | Invalid or missing API key | The Authorization header carries your key as `Bearer sk-…` — check for typos, extra whitespace, or an empty env var in the shell that runs your client. |
| 402 | Insufficient balance | Your wallet balance or the key's spend cap is exhausted. Top up, or raise the key's maxSpend in Dashboard → API Keys. |
| 403 | Forbidden | The key is disabled, or the request hit a permission boundary. Verify the key's status in the dashboard and confirm you're calling the right base URL for your client. |
| 404 | Unknown route or model | The path or model ID doesn't exist. Copy the exact model ID from the /models page — IDs are case-sensitive. |
| 429 | Rate limit exceeded | You hit the key's rateLimit / tokenLimitTpm ceiling or an upstream limit. Check Dashboard → Logs, slow the request rate, or contact support to raise limits. |
| 500 | Internal server error | Transient server-side failure. Retry with backoff; contact support if it persists. |
| 529 | Upstream overloaded | The model's upstream is saturated. If the error is retryable and another healthy provider serves the same exact model, Router One can try that route; otherwise retry with bounded backoff. |
| Timeout | No response in time | Long generations are normal for big prompts. Don't set aggressive client timeouts; check the final request metrics for end-to-end latency. |
Read the trace before guessing
Router One's customer-facing request row shows the final model and provider with tokens, cost, latency, and status. Dashboard → Logs filters by model and date, so you can see whether an error is isolated or recurring. It does not expose failed provider attempts or a fallback chain; share the request_id with support when those intermediate attempts need investigation.
Errors in Claude Code
Claude Code talks to the Anthropic-compatible endpoint at https://api.router.one — note: no /v1 suffix. Most 401/403s in Claude Code come from environment variables that are missing, exported in a different shell, or overridden by an earlier official-API login. Set all three variables and restart the terminal:
export ANTHROPIC_BASE_URL=https://api.router.one export ANTHROPIC_API_KEY=sk-your-router-one-key export ANTHROPIC_AUTH_TOKEN=sk-your-router-one-key
Errors in Codex CLI
Codex CLI speaks the Responses API wire format, which many OpenAI-compatible relays don't implement — that's why Codex 404s against them. Router One supports wire_api = "responses" natively. Point Codex at https://api.router.one/v1 via ~/.codex/config.toml and set OPENAI_API_KEY in the same shell. Full walkthrough on the Codex Responses API page.
FAQ
- My key looks correct but I still get 401. Why?
- The three usual causes: the env var is set in a different shell (or profile file) than the one running your client; the key was pasted with a trailing space or newline; or the client reads a different variable than the one you set. Print the variable in the same session right before launching the client to confirm.
- What's the difference between 402 and 429?
- 402 is about money: the wallet balance or the key's maxSpend cap is exhausted. 429 is about speed: too many requests or tokens per minute for the key's rateLimit / tokenLimitTpm, or an upstream limit. The request trace in Dashboard → Logs shows which one you hit.
- Do 5xx errors mean I have to write retry logic?
- An eligible 5xx or timeout can be retried on another healthy provider serving the same exact model, when one is available. That is not guaranteed for every error, so use bounded backoff for failures returned to your app and contact support if the pattern continues.
- Why does Claude Code return 403 while the same key works with curl?
- curl talks to the OpenAI-compatible endpoint; Claude Code needs the Anthropic-compatible base URL without the /v1 suffix, plus ANTHROPIC_AUTH_TOKEN set alongside ANTHROPIC_API_KEY. See the dedicated Claude Code 403 guide for the full checklist.
- Where do I see exactly which request failed and why?
- Dashboard → Logs shows the final request record with status, model, provider, tokens, and latency. Filter by model and time range to isolate it, then use its request_id when support needs to inspect failed intermediate provider attempts in operational logs.