Errors
Every code the gateway can return, generated from the same catalog the gateway itself uses.
Every API error carries a stable code and a message that ends in a URL. Each URL resolves to an anchor on this page, and the anchor id is the code.
This page is generated from the same catalog the gateway serves from. It cannot drift, because there is nothing to keep in sync.
{
"error": {
"message": "Rate limited: this key allows 60 requests/minute. Raise it at https://onerouter.dev/keys",
"type": "rate_limit_error",
"code": "rate_limited",
"param": null
}
}Not that you should retry immediately. Honour Retry-After where it is present, and back off where it is not. A non-retryable error needs a change from you first — retrying it unchanged will fail the same way.
Invalid API key. Keys start with `or-live-` and are created at https://onerouter.dev/keys, or with `POST /v1/keys`. A key from another gateway will not work here.Fix. Create a key at https://onerouter.dev/keys. Rotation with the recovery secret replaces the key immediately — there is no grace window, so swap it in one move.
Missing bearer token. Send your key as 'Authorization: Bearer or-live-...'.Fix. Send the header. A client that holds the key but omits it is almost always reading an unset environment variable — echo it before blaming the gateway.
Insufficient credit: this key's balance will not cover the request, so it was not sent and nothing was charged. Top up at https://onerouter.dev/payFix. Add credit. The message tells you which case you hit. A pre-request refusal names your balance and the worst-case estimate it could not cover, and nothing was sent or charged. A mid-stream stop names what the delivered tokens actually cost. The x-onerouter-balance-usd header on the 402 is the same available balance.
Unknown model 'claude-sonnet-5'. Did you mean 'anthropic/claude-sonnet-5'? Full list: https://onerouter.network/v1/catalogFix. Use an id from the catalog, in author/name form. The suggestion is computed from the closest published id, so an agent can correct itself without a human.
'onerouter/auto:code' has no model available for this request right now — every candidate was unavailable, not allowed on this key, or unable to price the request. Name a model directly, or retry shortly. Current picks: https://onerouter.dev/models/autoFix. Auto walked its ordered list and every candidate failed one of three tests. The resolution table is public; pick a model by name to bypass the router entirely.
No verified free route is available. This request was not switched to a paid model and nothing was charged. Availability: https://onerouter.dev/models/auto/freeFix. Retry later. The Open Tier never falls back to paid, so adding credit will not resolve this — name a paid model explicitly if you need the request served now.
Your Open Tier allowance is exhausted. Retry after the time in Retry-After. Quotas reset at 00:00 UTC.Fix. Wait for the reset. Every key on the account shares one allowance, so minting another key does not reset it, and adding credit does not raise it.
Rate limited: this key allows 60 requests/minute. Raise it at https://onerouter.dev/keysFix. Back off for the number of seconds in Retry-After, then retry the identical request. The message names both the limit and the knob — a 429 that names neither is a dead end.
This request exceeds the daily cap on budget 'nightly-agents' ($20.00/day, $19.94 used). Review it at https://onerouter.dev/docs/budgetsFix. Raise the named budget or wait for its window to reset. Open reservations count immediately, so concurrent requests cannot bypass a cap a serial request would have hit.
Request is 182,400 tokens but 'meta-llama/llama-3.3-70b-instruct' accepts 131,072. Models with larger context: https://onerouter.dev/modelsFix. Shorten the prompt or pick a longer-context model. The counts are named so you can tell how far over you are without instrumenting your own tokenizer.
Request body exceeds the 10 MB limit.Fix. Trim the request. A body this size is almost always an accidentally inlined file or a runaway conversation history. The edge refuses it before reading it all rather than buffering it into memory.
The upstream returned an error after we had begun streaming, so we could not move to another host without corrupting the response. Live status: https://onerouter.dev/providersFix. Retry the request. If output had barely started — under 50 tokens — the charge is written off automatically rather than billed for a response you cannot use.
No first token from any upstream within 30s, across 3 hosts. Live status: https://onerouter.dev/providersFix. Retry. Before the first byte reaches you we can and do switch hosts automatically; after it, we cannot.
'messages' must be a non-empty array. See https://onerouter.dev/docs/errors#invalid_requestFix. Check the field named in the message. On the Open Tier this also covers routing overrides — models, provider, route, fallbacks — which are refused rather than silently ignored. For base-URL mistakes, use https://onerouter.network/v1 with no endpoint suffix.
Embeddings are not served by this gateway. OneRouter serves text generation only.Fix. Move to /v1/chat/completions, /v1/responses or /v1/messages. Unsupported surfaces answer with a sentence rather than a 404 so a misconfigured client is told what to do instead of guessing.
This account is suspended. Contact https://onerouter.dev/support to resolve it.Fix. Contact support. Suspension follows a chargeback, a sanctions-screening hit, or an acceptable-use breach — the reply names which.
Internal server error.Fix. Retry, then report it with the receipt id from x-onerouter-receipt. This message carries no detail on purpose: an unhandled exception must never surface a stack frame that could carry prompt text into a response body or a log line.