GuidesRunning & maintaining

OpenRouter "Provider returned error": find the real cause

"Provider returned error" wraps the real provider's refusal. Where the inner message sits, and what context overflow, Gemini and 429 messages mean.

November 14, 2026The Everpod team
The short answer

“Provider returned error” is OpenRouter passing on a refusal from the company that actually runs the model (Google, Nvidia, DeepInfra and so on). It is a wrapper, not a cause. The provider’s own message sits inside it, in error.metadata.raw, with the provider named in metadata.provider_name, and most agents print only the wrapper. Find the full error body in your agent’s log, read the inner message, and fix that: usually a conversation too long for the model, a request shape the provider rejects, or the provider’s own rate limit.

What the full error looks like

An agent usually shows one line, such as “400 Provider returned error” or “Error: 422 Provider returned error”. The body behind it has this shape, here from a context overflow on a free Nvidia model, shortened:

{"error": {
  "message": "Provider returned error",
  "code": 400,
  "metadata": {
    "raw": "{\"error\":{\"message\":\"This model's maximum context length is 262144 tokens. However, your messages resulted in 262897 tokens. Please reduce the length of the messages.\"}}",
    "provider_name": "Nvidia",
    "is_byok": false
  }
}}
Copied

raw is the provider’s reply as it came back, a JSON string inside the JSON. OpenRouter’s errors documentation says provider_name, provider_code and raw identify who declined, and that the provider’s own error code appears in metadata.provider_code on errors other than 500s. The status on the outer line is a rough guide to the kind of refusal (400 for a request the provider will not take, 429 for a rate limit, 422 for one it could not process), but it is not always the provider’s own: the inner code can differ.

Two cases hide even that much. A 500 has its message replaced with a generic one, so there is nothing more to read. And an error that happens once a streamed reply has started arrives inside the stream with HTTP 200 and finish_reason: "error", so a tool that judges by status alone sees success followed by nothing.

Getting the inner message out of your agent

Agents differ in what they keep. The full body is usually in the agent’s log or verbose output rather than in the chat: OpenCode, for one, prints it with opencode run "hello" --print-logs, which sends one message and shows the provider call as it happens. Look for metadata near the error line.

When the inner message says the request itself is malformed, it helps to see what was actually sent. OpenRouter’s debug option with echo_upstream_body: true returns the request body as transformed for the provider. It works only on streamed requests and is meant for debugging, not for production traffic.

The inner messages agents meet most

The conversation is longer than the model’s context

This model's maximum context length is 262144 tokens. However, your
messages resulted in 262897 tokens. Please reduce the length of the messages.
Copied

A long agent session, a large file read into it, or many tool results add up until the model cannot take the request. It is the raw behind a Cline report on a free Nvidia model, and OpenRouter classes it as context_length_exceeded: input plus output beyond the model’s window. Retrying sends the same tokens and is refused again. Compact or start a fresh session, or pick a model with a larger window.

“Requests ending with a model turn are not supported”

Google refuses a Gemini request whose last turn is the model’s own. Agents trip it when a tool returns an image, such as a screenshot or an image file read from disk, and the image travels in a form that leaves the request ending on the model’s tool call. It was reported in OpenCode and in Hermes on the same day in October 2026, and in oh-my-pi it showed as “422 Provider returned error” while the provider’s own status was 400. The fix belongs in the agent (the reports propose sending the image in a following user message); until your agent has it, avoid image-bearing tool results on Gemini through OpenRouter, or use another model for that work.

“Gemini models require OpenRouter reasoning details to be preserved”

Gemini expects the reasoning data from its previous turn, including a thought_signature on tool calls, to be sent back with the next request. A tool or proxy that drops it gets this raw, with Google’s own “Function call is missing a thought_signature in functionCall parts” beside it, as Claude Code Router users found. It is a fault in whatever sits between you and OpenRouter: update it, or use a model that does not need the round trip.

The provider’s own rate limit

A 429 inside the wrapper can be the provider throttling or out of capacity rather than your account. OpenRouter’s limits page says its fallback routing already retries other providers for the same model before the error reaches you, so a 429 that does reach you means none of them took it. Adding fallback models, or relaxing any provider preferences you set, gives the request more places to go. On a model whose ID ends in :free, the cap may be OpenRouter’s own: 20 requests a minute, and 50 a day until the account has bought 10 credits, then 1,000. Kilo Code users see that as “Rate limit exceeded, try again later. 429 Provider returned error”, and an agent working through a task reaches 50 requests quickly.

Images the provider will not take

OpenRouter’s error vocabulary has separate types for an image that is too large, too small, in an unsupported format, or could not be downloaded, each a 400. The raw names which; the remedy is a smaller or converted image, or a model that accepts it. A model that takes no images at all is refused by OpenRouter itself, with “No endpoints found that support image input”.

When the wrapper is all there is

If no log holds more than “Provider returned error”, the status still narrows it. A 400 or 422 is about the request, so it fails the same way every time until the conversation, the attachment or the model changes; switching model is the quickest test. A 429 is about load or a cap, and clears with time or with another provider or model. A 500 has no detail to recover, and trying again later is the only move.

Give your AI agents a permanent cloud computer.

We set it up and secure it, so all you do is use them. Run Claude Code, Codex or any agent you use, more at once than your laptop can hold, and keep them working when it’s closed. Or have OpenClaw set up and run for you.

See the developer pod

From $24/mo · your own plan or API key

Get your OpenClaw agent

$29/mo, cancel anytime · model usage included