Rate Limits & Errors
The limits, and what each status code means.
A 429 can come from several layers:
- Our free-model cap: 1 request per minute, per free model, per user.
- Upstream limits: the provider behind a free model hit its own cap.
- Daily token budgets on some free pools, reset at midnight UTC.
- Tokens-per-minute caps, triggered by very large prompts.
- A per-user concurrency limit on parallel requests.
Paid models have no UnoRouter-imposed rate limits.
When the 1-per-minute cap fires you get standard rate-limit headers:
HTTP/1.1 429 Too Many Requests
Retry-After: 38
X-RateLimit-Limit: 1
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1783198478Retry-After is the seconds left in your window, not a flat 60. The message names the paid model, which has no limit.
Some paid models are offered free with a request size cap. Oversized prompts return 413: Request body too large for gpt-4.1 model. Max size: 8000 tokens.
The cap applies to the free route only. The paid model takes full-length prompts.
Errors return JSON in the OpenAI error format. code is a stable identifier. A request id is appended to every message:
{
"error": {
"message": "Model \"gpt-5.5-typo\" is not offered here. Check the model name for typos, or switch to a model from our supported list. (request id: 20260705...)",
"type": "new_api_error",
"code": "model_not_found"
}
}Include the request id in support tickets. It locates your request in the logs.
If you are still setting up your key or base URL, start with Quickstart
The status codes you will actually encounter:
| Code | Meaning | What to do |
|---|---|---|
400 | Invalid request: bad parameter, or a prompt blocked by moderation. | Fix the request. Retrying unchanged fails again. |
401 | Missing, invalid, expired or disabled key. | Check the Authorization header and the Tokens page. |
402 | This key's own spending limit is exhausted. | Raise the key's limit or create a new key. |
403 | Balance empty, model not allowed for this key, or IP not on the allowlist. | Top up, or check the key's model and IP restrictions. |
413 | Request exceeds the model's free trial size cap. | Shorten the prompt or switch to the paid model. |
429 | A rate limit fired (see the kinds below). | Wait for Retry-After seconds, then retry or switch models. |
500 | Something failed on our side or at the upstream provider. | Retry after a short wait. Report persistent 500s. |
503 | All providers busy, or the model name does not exist. | Read the message: busy clears in minutes, a typo does not. |
Two very different situations share status 503. The first is temporary congestion:
HTTP/1.1 503 Service Unavailable
{
"error": {
"message": "All providers for model \"kimi-k2.6:free\" are busy right now (they hit their rate limit). This is not a spelling error. Please try again in a little while, or switch to another model. (request id: 20260705...)",
"type": "new_api_error",
"code": "get_channel_failed"
}
}get_channel_failed means every free provider for that model is rate limited. It clears in minutes: retry or switch models. model_not_found means the name does not resolve; retrying never helps. Check for typos or the catalog.
Treat get_channel_failed as retryable and model_not_found as a hard error.
A model that vanished under load comes back on its own; to get pinged the moment it does, watch it in Notifications
If your key pins provider groups, a third 503 appears when only your pinned groups are down, see Group Pinning
Honor Retry-After on 429. Retry 503 get_channel_failed after a short wait, or switch models. Do not retry 400-class errors.
Failed and refused requests are never billed; how the pre-hold and refund work is covered in Account & Billing