Build

Errors

Find your error code below for its HTTP status, example message and next steps.

Auto Free refusals

429 free_quota_exceeded includes Retry-After. 503 auto_unresolvable means Auto Free is temporarily unavailable. Unsupported features return 400 invalid_request. None of these errors triggers paid fallback.

See the Auto Free API guide for setup, account limits, and the separate chat trial.

Code	HTTP	Retry as-is
trial_exhausted	402	No
trial_temporarily_unavailable	503	No
request_in_progress	409	No
insufficient_credits	402	No
invalid_api_key	401	No
unknown_model	404	No
model_not_allowed	403	No
model_alias_unavailable	503	Yes
model_unavailable	503	Yes
no_available_route	503	Yes
upstream_capacity_exceeded	503	Yes
upstream_rate_limited	503	Yes
auto_unresolvable	503	Yes
free_quota_exceeded	429	Yes
rate_limited	429	Yes
usage_limit_exceeded	429	Yes
spend_limit_exceeded	403	No
guardrail_blocked	403	No
context_too_long	400	No
provider_policy_rejected	400	No
upstream_response_invalid	503	Yes
upstream_error	502	Yes
image_request_failed	502	No
images_unavailable	503	Yes
upstream_capacity_unavailable	503	Yes
admission_unconfirmed	502	Yes
request_timeout	504	Yes
account_suspended	403	No
invalid_request	400	No
payload_too_large	413	No
overloaded	503	Yes

Retry as-is means the identical request may succeed if sent again. Everything else needs a change first: credits, a key, a model ID, a smaller body.

Free allowance used

402 · trial_exhausted

Example message, exactly what your client will show

Your free messages are used. Add credits and explicitly choose paid chat at https://minirouter.sh/chat.

Fix: Add credits, then choose paid chat before sending again.

Free chat unavailable

503 · trial_temporarily_unavailable

Example message, exactly what your client will show

Free chat is temporarily unavailable. No paid request was substituted. Check availability at https://minirouter.sh/chat.

Fix: Wait and check the offer, or explicitly choose paid chat.

A chat request is settling

409 · request_in_progress

Example message, exactly what your client will show

Your previous free request is still running or settling. Check its receipt at https://minirouter.sh/chat.

Fix: Wait for the previous request to settle before sending another.

Insufficient credits

402 · insufficient_credits

Example message, exactly what your client will show

Insufficient credits: your available balance is $4.23, below this request's worst-case estimate of $5.10, so it was not sent and nothing was charged. Top up at https://minirouter.sh/dashboard/billing

Team account

Insufficient credits: your team's available balance is $4.23, below this request's worst-case estimate of $5.10, so it was not sent and nothing was charged. Only the team owner can top up. Top up at https://minirouter.sh/dashboard/billing

Fix: Add credits. The message says which case you hit: a pre-request refusal names your available balance and the worst-case estimate it could not cover (nothing was sent or charged); a mid-stream stop names what the delivered tokens cost. The X-Minirouter-Balance-Usd header on the 402 reports your available balance.

Invalid API key

401 · invalid_api_key

Example message, exactly what your client will show

Invalid API key. Keys start with `mr-live-` and are created at https://minirouter.sh/dashboard/keys. If you rotated recently, the previous key keeps working for a 24-hour grace window, then stops.

Fix: Create or rotate a key in the dashboard. The old key works for 24 hours after rotation. Revoke a key to disable it immediately.

Unknown model

404 · unknown_model

Example message, exactly what your client will show

Unknown model 'deepseek-v3'. Did you mean 'deepseek/deepseek-v3'? Full list: https://minirouter.sh/api/v1/models

Fix: Copy an exact model ID from the catalog or use the suggestion in the error.

Model not allowed on this key

403 · model_not_allowed

Example message, exactly what your client will show

'openai/gpt-5.5' exists but this API key's policy does not allow it. Did you mean 'openai/gpt-5.5-mini'? Allowed models are set per key at https://minirouter.sh/dashboard/keys and per guardrail at https://minirouter.sh/dashboard/guardrails

Fix: Pick a model the key allows, or widen the key or guardrail allowlist. The account-wide list on /dashboard/routing also applies.

Model alias temporarily unavailable

503 · model_alias_unavailable

Example message, exactly what your client will show

The mapping for 'example/model-alias' could not be resolved safely. Use a concrete model ID or try again shortly. See https://minirouter.sh/models

Fix: Use the model ID from the catalog, or try the alias again shortly.

Model temporarily unavailable

503 · model_unavailable

Example message, exactly what your client will show

The provider could not complete your request for 'meta/llama-3.3-70b'. Try again shortly or choose another model. Status: https://minirouter.sh/status

Fix: Check the status page, then try again or choose another model allowed by your account settings.

No available provider route

503 · no_available_route

Example message, exactly what your client will show

No eligible provider route is available for 'deepseek/deepseek-v4.1-flash' with your current settings. Try again shortly or review your model and provider restrictions at https://minirouter.sh/dashboard/routing.

Fix: Review model and provider restrictions on your account, API key, and request, or check model availability before retrying.

Provider at capacity

503 · upstream_capacity_exceeded

Example message, exactly what your client will show

'deepseek/deepseek-v4.1-flash' is temporarily at capacity. Try again shortly or choose another model. Status: https://minirouter.sh/status

Fix: Wait before retrying, or choose another model allowed by your account settings. This is provider capacity, not your account rate limit.

Provider rate limit

503 · upstream_rate_limited

Example message, exactly what your client will show

The provider is temporarily rate limiting requests for 'deepseek/deepseek-v4.1-flash'. Try again shortly or choose another model. Status: https://minirouter.sh/status

Fix: Wait before retrying, or choose another model allowed by your account settings. Raising your MiniRouter key limit will not change the provider limit.

No model available for auto

503 · auto_unresolvable

Example message, exactly what your client will show

'minirouter/auto:code' has no model available for this request right now (every candidate is unavailable or not allowed on this key). Name a model directly, or retry shortly. Current auto picks: https://minirouter.sh/models/auto

Fix: Auto walks an ordered list of models and every one was unavailable, not allowed on your key, or unable to price this request. The page lists the current candidates; pick one by name to bypass auto.

Free allowance exhausted

429 · free_quota_exceeded

Example message, exactly what your client will show

Your free allowance is exhausted. Retry after the time in Retry-After. See https://minirouter.sh/models/auto.

Fix: Wait until the quota resets. All keys on this account share the free allowance; creating another key does not reset it.

Rate limited

429 · rate_limited

Example message, exactly what your client will show

Rate limited: this key allows 60 requests/minute. Raise it at https://minirouter.sh/dashboard/keys. Limits: https://minirouter.sh/docs/rate-limits

Fix: Wait for Retry-After. Raise key limits in the dashboard. Per-address limits cannot be raised: use a valid key after invalid-key requests, or cache the model list after too many catalog reads.

Usage limit reached

429 · usage_limit_exceeded

Example message, exactly what your client will show

This request exceeds the requests-per-minute limit configured for this API key. Review it at https://minirouter.sh/dashboard/keys

Fix: Raise the named account or API-key rate limit (requests per minute, tokens per minute or concurrent requests), or wait a minute and retry. In-progress requests count toward the limit. Spend caps return spend_limit_exceeded instead.

Spend limit reached

403 · spend_limit_exceeded

Example message, exactly what your client will show

This request exceeds the daily spend limit configured for this API key. It resets at 2026-09-16T00:00:00Z. Review it at https://minirouter.sh/dashboard/keys

Fix: Raise the named limit, move the key to a guardrail with a larger budget, or wait for the window to reset. In-progress requests count toward the limit. Retrying before the reset returns the same error.

Blocked by a guardrail

403 · guardrail_blocked

Example message, exactly what your client will show

A guardrail on this API key blocked the request: prompt injection patterns detected (ignore_previous_instructions). Nothing was sent to a provider and nothing was charged. Manage guardrails at https://minirouter.sh/dashboard/guardrails Docs: https://minirouter.sh/docs/guardrails

Fix: Remove the flagged content, change the filter from block to redact, or unassign the guardrail from this key. The message names the detector, never the text it matched.

Context too long

400 · context_too_long

Example message, exactly what your client will show

Request is 182,400 tokens but 'meta/llama-3.3-70b' accepts 131,072. Models with larger context: https://minirouter.sh/models/long-context

Fix: Shorten the prompt or pick a longer-context model.

Provider policy rejection

400 · provider_policy_rejected

Example message, exactly what your client will show

The upstream provider rejected this request during content inspection. Retrying the same request is unlikely to help. Details: https://minirouter.sh/errors/provider_policy_rejected

Fix: Review the request against the provider policy. If the rejection appears incorrect, contact support with the request ID.

Invalid upstream response

503 · upstream_response_invalid

Example message, exactly what your client will show

The provider answered for 'deepseek/deepseek-v4-flash-0731' with a response MiniRouter could not validate (responses_invalid_response_status), so it was not returned. Try again shortly; nothing beyond the provider's own usage is charged. Status: https://minirouter.sh/status

Fix: Retry, or choose another model. If it repeats, contact support with the request ID; the reason names the failed check.

Upstream error

502 · upstream_error

Example message, exactly what your client will show

The upstream provider returned an error after we had begun streaming, so we could not retry on another provider without corrupting the response. Details and live status: https://minirouter.sh/status

Fix: Retry the request. If output had barely started (under 50 tokens) the charge is written off automatically.

Image request failed

502 · image_request_failed

Example message, exactly what your client will show

We could not complete this image request. A dispatched generation may still incur a charge. Use the request ID to check its billing status before submitting another image request. Details: https://minirouter.sh/errors/image_request_failed

Fix: Check GET /v1/images/status?request_id=YOUR_REQUEST_ID with the same account. Final charges cannot exceed the original hold; unresolved holds release at the cost deadline. We do not automatically regenerate images.

Images unavailable

503 · images_unavailable

Example message, exactly what your client will show

Image requests are currently unavailable. This request was not sent to the provider. Live status: https://minirouter.sh/status

Fix: Check service availability and try again later. An existing image request may still be awaiting its final provider cost.

Upstream capacity paused

503 · upstream_capacity_unavailable

Example message, exactly what your client will show

Provider capacity is temporarily unavailable. This request was not sent to the provider and nothing was charged; your hold has been released. Retry shortly. Live status: https://minirouter.sh/status

Fix: Wait for the Retry-After delay, then try again. Check the status page if the problem persists.

Request could not start

502 · admission_unconfirmed

Example message, exactly what your client will show

We could not start this request, so it was not sent to the provider. Nothing was charged; the temporary hold releases automatically within 20 minutes. Live status: https://minirouter.sh/status

Fix: Try again. Nothing was charged for this request. Any temporary hold is released automatically within 20 minutes.

Request timed out

504 · request_timeout

Example message, exactly what your client will show

No complete response arrived within 110s after 1 upstream attempts. For long generations, use stream=true with an appropriate output limit. Live status: https://minirouter.sh/status

Fix: For long generations, use streaming and a realistic output limit. A timed-out request may still have run upstream; do not assume an automatic retry is free or that provider fallback was available.

Account suspended

403 · account_suspended

Example message, exactly what your client will show

This account is suspended. Contact https://minirouter.sh/support to resolve it.

Fix: Contact support. Suspension follows a chargeback, a sanctions-screening hit, or an acceptable-use breach.

Invalid request

400 · invalid_request

Example message, exactly what your client will show

'messages' must be a non-empty array. See https://minirouter.sh/docs/errors#invalid_request

Fix: Check the field named in the message. Remove unsupported fields or simplify an oversized or deeply nested schema. If your client generates the request, contact support with the model, client version, request ID and field path. For base-URL errors, use https://api.minirouter.sh/v1 or https://api.minirouter.sh without a /chat/completions suffix.

Request body too large

413 · payload_too_large

Example message, exactly what your client will show

Request body exceeds the 32 MB limit. Long contexts belong in the prompt, not in attachments — see https://minirouter.sh/docs/rate-limits

Fix: Reduce the request size by shortening the conversation history or removing large attachments.

Gateway overloaded

503 · overloaded

Example message, exactly what your client will show

The gateway is at its concurrent-request ceiling, so this request was not sent to a provider and nothing was charged. Retry after the Retry-After delay. Live status: https://minirouter.sh/status

Fix: Retry after Retry-After (5 seconds). This is the edge protecting itself, not a limit on your key: it refuses before placing any hold, so nothing is reserved or charged. If it persists, check the status page.