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 nRouter API request returns a structured JSON error envelope containing a machine-readable code and descriptive message. Branch deterministically on code rather than parsing message text across status codes, rate-limit headers (x-nr-limit-source, Retry-After), and failover rules.
{ "error": { "message": "Invalid API key provided.", "type": "authentication_error", "code": "invalid_api_key" } }Status & error codes
| Status / Code | Meaning |
|---|---|
400 · fallback_not_allowed / guardrail_not_found | Invalid payload, unpermitted fallback target, or unknown guardrail ($0 spent). |
400 · guardrail_blocked | Blocked in-path before any provider call (x-nr-guardrails: blocked, $0 spent). |
400 · input_too_large / max_output_tokens_too_large / image_input_unsupported | Prompt, output cap, or image input exceeds model limits. |
401 · invalid_api_key | Missing, expired, or revoked key (x-nr-auth-reason states why). |
402 · insufficient_credits / budget_exceeded | Credit balance or budget ceiling reached (Billing). |
403 · key_model_not_allowed / model_denied_by_* | Key or organization allowlist does not permit the requested model. |
404 · model_not_found | Requested model or withdrawn Smart Router alias is unknown. |
429 · rate_limit_exceeded | RPM/TPM or plan window crossed — check x-nr-limit-source and wait Retry-After. |
500 / 503 · service_unavailable | Upstream or dependency unavailable (retry as-is if x-nr-guardrails: unavailable). |
Rate limits & failover
- Rate limits: Enforced per key (RPM and TPM), team, and organization. Fallback chains consume one credit hold and one rate-limit slot.
- Failover: Triggers only on configured fallback chains for 429, 503, Anthropic 529, 401/404 from a misconfigured deployment, connect failure, or first-byte timeout (max 3 provider calls per request).
Frequently asked questions
Should I retry a failed request?
Retry 429 after Retry-After and 503 (x-nr-guardrails: unavailable) as-is; never retry 400 errors without fixing the request.
Does nRouter retry automatically?
Yes, when a fallback chain is configured, up to 3 total provider calls on upstream 429, 503, Anthropic 529, or connect/first-byte failures.
What is the difference between a 402 for credits and one for a budget?
insufficient_credits means your credit balance is low; budget_exceeded means a spend cap refused the call (x-nr-limit-source names the ceiling).
A guardrail blocked my request. Was I charged?
No — guardrail_blocked (400) refuses before any provider call and spends $0.
Should my code branch on the error message?
No — always branch on the stable error.code field.
Chat Completions · Authentication · Troubleshooting · Per-Request Options · Support