---
title: "Errors"
description: "Every gateway error code, exact message shape and recovery step."
canonical_url: "https://minirouter.sh/docs/errors"
markdown_url: "https://minirouter.sh/docs/errors.md"
last_updated: "2026-08-04"
---

# Errors

Every API error contains a URL, and each URL resolves to an anchor on this page. The anchor id is the error code. This page is generated from the same catalog used by the gateway.

## insufficient_credits

HTTP 402: Insufficient credits. Not retryable.

Example message:

    Insufficient credits: this response stopped because your balance reached $0. You were charged $0.0031 for the tokens delivered. Top up at https://minirouter.sh/dashboard/billing

Fix: Add credits. Prevention matters more than the message: we return a pre-request 402 once your balance is below the estimated cost, emit an X-Minirouter-Balance-Usd header on every response, and email at 20% and 5% of a 7-day burn.

## invalid_api_key

HTTP 401: Invalid API key. Not retryable.

Example message:

    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. Rotation keeps the old key alive for 24 hours so a running agent is not bricked mid-task; Revoke is the instant kill.

## unknown_model

HTTP 404: Unknown model. Not retryable.

Example message:

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

Fix: Use a model id from the catalog. The did-you-mean suggestion is computed from the closest published id.

## model_unavailable

HTTP 503: All upstreams unavailable. Retryable.

Example message:

    All upstream providers for 'meta/llama-3.3-70b' are failing right now (we tried together, fireworks, deepinfra). Live status: https://minirouter.sh/status. Working alternatives at this moment: 'deepseek/deepseek-v3', 'mistral/ministral-14b'.

Fix: Retry, or switch to one of the named alternatives. Suggesting a live alternative inside the error is deliberate — an agent can act on it without a human.

## rate_limited

HTTP 429: Rate limited. Retryable.

Example message:

    Rate limited: this key allows 60 requests/minute. Raise it at https://minirouter.sh/dashboard/keys

Fix: Raise the per-key limit, or slow down. Never rate-limit without naming both the limit and the knob.

## usage_limit_exceeded

HTTP 429: Usage limit reached. Retryable.

Example message:

    This request exceeds the daily spend limit configured for this {scope}. Review it at https://minirouter.sh/dashboard/{settingsPath}

Fix: Raise the named account or API-key limit, or wait for its current window to reset. Open reservations count immediately, so concurrent requests cannot bypass the limit.

## context_too_long

HTTP 400: Context too long. Not retryable.

Example message:

    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.

## upstream_error

HTTP 502: Upstream error. Retryable.

Example message:

    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.

## request_timeout

HTTP 504: Request timed out. Retryable.

Example message:

    No first token from any upstream within 30s, across 3 providers. Live status: https://minirouter.sh/status

Fix: Retry. Before the first byte reaches you we can and do switch providers automatically; after it, we cannot.

## account_suspended

HTTP 403: Account suspended. Not retryable.

Example message:

    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

HTTP 400: Invalid request. Not retryable.

Example message:

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

Fix: Fix the request body. The most common cause is a base-URL mistake: we accept both https://api.minirouter.sh/v1 and https://api.minirouter.sh, but not a /chat/completions suffix in the base URL itself.

## payload_too_large

HTTP 413: Request body too large. Not retryable.

Example message:

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

Fix: Trim the request. A body this size is almost always an accidentally inlined file or a runaway conversation history; the edge refuses it before reading it all rather than buffering it into memory.