Common errors

Errors from the Mel relay follow one shape: a JSON body of {"error": "<machine_code>", "message": "<human text>"} with a matching HTTP status. Mid-stream failures on an agent turn arrive as an {"event": "error"} line instead, and the message surfaces inline in the conversation. This page decodes the ones you're most likely to meet.

If the agent can't reach the backend at all, start with Agent connectivity instead.

"all candidate models are unavailable right now — please try again shortly"

The relay never depends on a single provider: when a model is rate-limited or erroring, it fails over down a chain of alternative models across providers and keeps your turn going. This error means the entire chain was exhausted — every candidate was unavailable at that moment (typically a burst of simultaneous rate limits or a multi-provider incident).

There's nothing to fix on your side. Wait a short while and retry; provider rate limits clear on their own. If it persists for a long time, tell us.

"unknown model '…'"

The model you requested isn't in the catalog. Two common causes:

• A stale or mistyped model id — check the model picker (or Models & routing) for current ids.
• Treating a routing bias as a model id. There is no auto-genius or auto-efficient model: routing tiers are the separate bias field. Send "model": "auto" with "bias": "genius" (or "cost-efficient" / "responsive"). In the app, this is the Auto-mode submenu of the model picker — you never type these by hand.

401 unauthorized / daily limit reached

The Mel agent needs a signed-in Mel account — sign-up is self-serve and free.

• 401 {"error": "unauthorized"} — no valid session. Sign in from the app; if you were signed in, your token may have been invalidated — sign in again. Don't have an account yet? Sign up in the same panel — it's instant.
• Daily free limit reached — on the Free plan the agent has a daily request quota. When it's used up, the app tells you and you can bring your own provider key to continue for free, or upgrade to Pro to remove the daily limit. See Billing & usage.

"images attached, but no vision-capable model is configured"

Full text: images attached, but no vision-capable model is configured — add a GEMINI_API_KEY or OPENAI_API_KEY to the relay, or remove the images.

Image turns must land on a vision-capable model. If you pin a non-vision model and attach images, the relay upgrades that one turn to a vision model and tells you so with a visible router notice — it never silently drops your attachments. This error only appears when no vision model is configured at all, which in practice means a self-hosted relay with no vision-capable provider key. On the hosted relay you shouldn't see it; locally, add a Gemini or OpenAI key to the relay's .env. See Image attachments.

413 payload_too_large

{"error": "payload_too_large",
 "message": "request body is N bytes; this relay accepts at most 16000000"}

The request body exceeded the relay's 16 MB cap. Realistic agent payloads sit far below this — a full 150k-token context is well under 1 MB of JSON — so hitting it usually means very large image attachments or a runaway third-party client. Trim the attachments or the message list.

400 bad_request (before the stream starts)

A request body the relay couldn't parse. The message names the required fields and accepted shapes — it's aimed at API users; the Mel app itself always sends valid bodies.

Still stuck?

Copy the exact error text and see Getting help.