When an OpenRouter free model stops responding, first check whether the problem is your request, your account allowance, or the model's availability. Another verified free model may help with an unavailable model. It will not restore an exhausted account-wide daily allowance.
The workflow below keeps paid models out of the recovery path. It is a suggested application design, not an OpenRouter feature that you can enable with one switch.
Start with the error you actually received
| What you see | Check next | What to do |
|---|---|---|
| Invalid credentials or an authorization error | The API key and account access | Fix access before trying another model. |
| Invalid request or unsupported parameter | The model's supported inputs and options | Correct the request. Keep any requirement essential to your task. |
| HTTP 429 | Error details, remaining allowance, and any retry instructions | Wait when required. Distinguish an account limit from a provider capacity problem. |
| HTTP 502 or 503 | The error message and routing restrictions | An eligible free alternative may help; availability is not guaranteed. |
| HTTP 402 | The exact route, account balance, and key credit settings | Investigate the account condition. Do not silently add credits or select a paid model. |
| A response stops partway through | The response body or streaming error | Keep the output as incomplete and check it before reuse. |
OpenRouter's error reference explains these responses. Record the status and a redacted error message. Do not put API keys or private prompts into public logs.
Confirm that the replacement really is free
OpenRouter lists free variants separately. A model supports :free only if that variant exists; appending the suffix to an arbitrary model name does not create a free version. A paid base model and its free variant can differ in availability and limits. See the free-variant documentation.
Before adding a candidate to your application's approved list:
- Find its exact identifier in the current catalog.
- Check every price relevant to your request, including any applicable pricing conditions.
- Check the input type, context capacity, output limits and required parameters.
- Exclude it if the information needed to establish zero cost is missing or unclear.
The Models API reference describes the metadata available for these checks. A catalog entry is not a promise that a request will succeed.
For example, if your application requires structured output, do not quietly remove that requirement to make a different model accept the request. Choose a compatible candidate or leave the task waiting. Likewise, do not estimate an output allowance from context length alone: provider output limits also matter.
Separate quota exhaustion from a busy provider
Check the authenticated GET /api/v1/key response for free_model_daily_requests, including its used, limit and remaining values. Do not treat credit-spending fields as request counts, and do not assume every account has the same allowance.
If the applicable daily allowance is exhausted, save the task and wait for the relevant reset. Changing API keys or cycling through model names is not a way to bypass an account limit.
For temporary rate limits, respect Retry-After when present. Otherwise use a bounded delay that increases between attempts. Check the error details to distinguish platform limits from upstream provider limits. These distinctions and account-credit conditions are covered in the limits documentation.
Try a free alternative without introducing paid routing
OpenRouter supports an ordered models list for fallback between models. If an earlier model fails, routing can try a later one. The response identifies the model used, and pricing follows that model. See model fallback behavior.
For a free-only workflow, every entry in that list must pass your free-model checks. Do not copy a documentation example's paid model list into your application unchanged. An application can also try its approved candidates one at a time; this makes its own attempt count and stop conditions easier to inspect.
This corrects an important distinction: switching to another verified free model is allowed by this workflow; switching to a paid model is not. A fallback is still subject to account limits, compatibility and your routing settings.
A small recovery policy you can adapt
Suppose a queued task needs a complete text summary. As an application policy, you allow at most two attempts per run and one approved free alternative. These are example limits you choose, not provider guarantees.
- Save the task with a stable identifier before sending it.
- Try the selected, verified free model once.
- If the response requests a delay, schedule the next attempt after that delay. Do not immediately send the alternative.
- If the model is unavailable and account allowance remains, try the compatible free alternative within the two-attempt budget.
- Validate the result against the original task. A successful HTTP response is not proof of accurate or complete content.
- Save a successful result once. If both attempts fail, preserve the task and its next retry time instead of running an endless loop.
For streamed output, keep partial text separate from the accepted result. A late error can occur after the initial successful HTTP status. Do not join an incomplete answer to a retry and assume the combined text is valid. The streaming error guidance explains how those failures are reported.
The useful outcome is either a checked result or an honestly reported wait. Free capacity cannot be guaranteed, and an unavailable free service is not permission to spend money automatically.
Sources and correction
Updated 22 September 2026 using the official documentation linked above. This revision removes contradictory fallback advice, an oversimplified output-limit formula, repetitive checklists and an unrelated image. The two-attempt workflow is a hypothetical design example, not a benchmark or a claim of a live provider test. This guide was prepared with AI assistance. Report an error.