Errors & Rate Limits

Every nRouter error returns one JSON shape with a machine-readable code: the status codes, the error codes, the rate-limit headers, and the retry rules.

Every failed request returns an error object with a machine-readable code. Branch on the code in your client — not on the message text.

{
  "error": {
    "message": "Invalid API key provided.",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

Status codes

Status	Meaning
400	The request was refused before any provider call — invalid shape, a fallback or guardrail refusal, or a blocked prompt. Nothing is spent.
401	Invalid, missing, expired, or revoked API key.
402	Insufficient credits to reserve the request.
403	The key lacks permission for the requested resource or model.
404	Model not found — or not enabled for your organization.
429	A rate limit or usage window was crossed — wait for `Retry-After`.
500 / 503	Provider or dependency unavailable.

Error codes

Code	When
`invalid_api_key` (401)	Key is wrong, missing, or revoked. The `x-nr-auth-reason` header says why (expired, blocked, IP not allowed, and more).
`insufficient_credits` (402)	Balance too low for the reservation — top up in Billing.
`model_not_found` (404)	Unknown model name — including the Smart Router aliases withdrawn on 2026-10-15.
`fallback_not_allowed` (400)	A fallback target your key can't route to, or fallbacks sent with `nrouter/auto`.
`guardrail_blocked` (400)	A guardrail refused the request before any provider call (header: `x-nr-guardrails: blocked`).
`guardrail_not_found` (400)	A `nrouter_guardrails` entry your organization doesn't own or hasn't enabled.
`input_too_large` / `max_output_tokens_too_large` (400)	The prompt or requested output exceeds the model's declared limits.
`image_input_unsupported` (400)	An image sent to `nrouter/auto` when no auto-routing model on the endpoint accepts images.
`rate_limit_exceeded` (429)	RPM/TPM or a usage window crossed — see `x-nr-limit-source`.
`service_unavailable` (503)	A required dependency was unavailable. With `x-nr-guardrails: unavailable`, a guardrail couldn't run and the request was refused unjudged — retry it as-is.

Rate limits

Limits are enforced per key — requests per minute (RPM) and tokens per minute (TPM), plus organization and budget ceilings.
A 429 tells you which ceiling refused in x-nr-limit-source (key, team, user, budget, a plan window, or capacity) and how long to wait in Retry-After.
Fallbacks don't multiply your limits: a request with fallbacks still uses one credit reservation and one rate-limit slot.

Retries & failover

The gateway fails over for you only on 429, 503, Anthropic 529, or a connect failure — and only where a fallback chain exists.
At most 3 provider calls per request, however the chain resolves.
Retry yourself on 429 (after Retry-After) and on the unjudged 503 above; fix 400s instead of retrying them.

Next Steps

Chat Completions — The full request and header reference
Authentication — How API keys and auth work
Per-Request Options — Fallbacks and per-request settings