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.

"Mel couldn't reach any AI provider for this request"

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, 402 out of credits, 429 rate limited

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.
• 402 credits_exhausted / "This plan has no hosted AI credits" — the Free plan grants no hosted-AI credits: add your own provider key in Settings → AI → Provider API keys and the agent keeps working, billed to your provider rather than to Mel. On a paid plan this means the monthly allotment is spent — buy an add-on pack or wait for the reset. See Billing & usage.
• 429 rate_limited — a fair-use ceiling, not a billing one. It applies on every plan, including when you bring your own key, and is set far above what a person working hard reaches; a per-minute ceiling is waited out inside your turn rather than ending it. If you see this, wait and retry.

"No available model can read images right now"

Full text: No available model can read images right now — none of the configured models is vision-capable. Send this turn without the image and describe it instead, or ask the operator to add a GEMINI_API_KEY or OPENAI_API_KEY.

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 appears when none of the keys the request can use reaches a vision-capable model. On a self-hosted relay that means no Gemini or OpenAI key in the relay's .env. On the hosted relay it can happen on your own provider key when you only added a text-only provider such as Groq: add a key for a provider with a vision model (for example Gemini or OpenAI), or send the turn without the image. 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.