Platform Guide

Errors & Rate Limits

What each status code means and what to do about it.

The error format

Errors come back as JSON in the OpenAI error format. The message states what happened, code is a stable machine-readable identifier, and a request id is appended to every message:

json

{
  "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"
  }
}

Always include the request id when you contact support or open a Discord ticket. It lets us find your exact request in the logs.

Status codes at a glance

The status codes you will actually encounter:

Code	Meaning	What to do
`400`	Invalid request: bad parameter values (for example max_tokens below the model minimum) or a prompt blocked by content moderation.	Fix the request. Retrying unchanged will fail again.
`401`	Key problem: missing, invalid, expired or disabled API key.	Check the Authorization header and your key on the Tokens page.
`402`	This key's own spending limit is exhausted.	Raise the key's limit or create a new key.
`403`	Access denied: account balance empty, model not allowed for this key, or your IP is not on the key's allowlist.	Top up, or check the key's model and IP restrictions.
`413`	Request too large for this model's free trial 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; persistent 500s are worth a report.
`503`	All providers for the model are busy, or the model name does not exist.	Read the message: busy resolves in minutes, a typo does not.

503: busy vs unknown model

Two very different situations share status 503. The first is temporary congestion:

text

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"
  }
}

The code get_channel_failed (all providers busy) means every free provider for that model is momentarily rate limited. This auto-recovers within minutes: retry or switch models. The code model_not_found (not offered here) means the model name itself does not resolve, and retrying will never help. Check for typos or look up the current name in the catalog.

Treat 503 with get_channel_failed as retry/fallback and 503 with model_not_found as a hard error in your client.

The kinds of rate limits

A 429 can come from several layers:

Our free-model cap: 1 request per minute per free model per user. A fairness cap so shared pools survive peak hours.
Upstream provider limits: the provider behind a free model hit its own cap ("temporarily rate-limited upstream").
Daily token budgets on some free pools; these reset at midnight UTC.
Tokens-per-minute caps that trigger on very large prompts.
A per-user concurrency limit when too many requests run in parallel.

Paid models have no UnoRouter-imposed rate limits.

The free-model limit in detail

When our 1-per-minute cap fires you get standard rate-limit headers, so clients can back off precisely:

text

HTTP/1.1 429 Too Many Requests
Retry-After: 38
X-RateLimit-Limit: 1
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1783198478

Retry-After is dynamic: the actual seconds left in your window, not a flat 60. The error message also names the paid twin of the model, which has no limit.

Trial size caps

Some normally-paid models are offered free with a request size cap. Oversized prompts get 413 with a message like: Request body too large for gpt-4.1 model. Max size: 8000 tokens.

The cap applies to the free trial route only; the paid model takes full-length prompts.

Retry guidance

Honor Retry-After on 429. Retry 503 get_channel_failed after a short wait, or fall back to another model. Do not retry 400-class errors, they are deterministic.

Failed and refused requests are not billed: any pre-hold on your balance is refunded when the request errors.