OpenRouter Free Model Not Working? Diagnose the Error Before Switching Models
The quick answer
When an OpenRouter free model stops responding, save the error and try one short request with the same model. Switching immediately makes it harder to tell whether the problem was the model, your client, the request size or your account.
Build your budget shortlistIn this guide
If the error points to an allowance, compare what your account shows with the listed OpenRouter Free conditions and source links.
A blank answer, a context error and a daily limit can all look like 'the model isn't working' in a chat app. They need different fixes. The quickest way forward is to narrow the failure down before you start changing settings.
Capture enough evidence to distinguish failures
Write down the time, client name and version, exact requested model ID, HTTP status, and a sanitized error category. If a response includes a request identifier, keep it for support. Do not paste an API key, private prompt, or raw provider payload into a public issue.
Use the following table as a triage aid, based on OpenRouter's error reference. Status alone is not a complete diagnosis: inspect the structured error and any applicable metadata. Official error documentation.
| Signal | First investigation | Avoid doing immediately |
|---|---|---|
| 400 | Request shape, parameters, and context size | Repeatedly resending the same payload |
| 401 | The configured credential | Publishing the key for help |
| 402 | Credits and key restrictions | Assuming all free endpoints require payment |
| 403 | Permissions, budgets, or moderation details | Assuming every refusal means exhausted quota |
| 429 | Platform allowance or upstream throttling | Launching many parallel retries |
| 502 or 503 | Provider availability and eligible routing | Rewriting the entire integration |
The table suggests where to look; the actual error message decides which branch is relevant.
Reduce the request to a controlled example
Try one short, non-sensitive text prompt with the same model ID. Remove optional tools, images, structured-output requirements, and extra plugins for this diagnostic request. If it succeeds, restore one feature at a time. This isolates a compatibility problem without pretending that a short successful answer proves the complete workflow works.
Keep the original failing request private for comparison. Note what changed between attempts. A useful record might say: “Short text works; adding tool definitions fails before generation.” That is much more actionable than “free models are broken.”
If the short request still fails, compare the exact ID with the live catalog. Do not borrow a year-old configuration snippet without checking whether its endpoint still exists. A familiar model family name is insufficient because a free variant is a separate catalog entry. Official free-variant reference.
A 429 does not always mean the daily allowance is gone
OpenRouter distinguishes platform rate limits from upstream provider throttling. Its limits reference recommends honoring Retry-After when present and checking the key endpoint for remaining free requests. A negative account balance can also affect free-model access. Official limits and account diagnostics.
If an allowance has been exhausted, stop the job and preserve progress. If the evidence indicates temporary provider congestion, use a small, bounded retry policy with increasing delays. Give the user a visible “waiting” state and an option to cancel. Never make an unlimited retry loop the default recovery behavior.
Treat changing models as a separate decision. A fallback can be useful for an interchangeable summarization task, but may invalidate a controlled model comparison. It can also alter cost if a paid entry is included. Decide whether the current task permits those changes before enabling automatic switching.
Context failures need a smaller relevant request
When the error identifies context or output length, inspect what the client actually sends. A screen showing one recent message may conceal a long conversation history, repository files, tool output, or instructions attached by the application.
Make a compact continuation note containing the task, decisions already made, relevant files, and the next action. Start a fresh attempt with that note and the smallest necessary evidence. Keep the original conversation available locally rather than repeatedly attaching everything.
For a code issue, a minimal failing example plus the error can be more useful than an entire repository. For document work, send the relevant passage and the required output format. These are troubleshooting techniques, not guarantees that a smaller model will understand the task.
Check whether the response actually finished
A client should inspect stream completion, not merely display the first tokens. OpenRouter documents errors that arrive after streaming has begun, when the HTTP response can no longer change status. Streaming error handling.
Do not automatically apply half a code patch or save a partial JSON answer as a successful result. Mark the attempt incomplete, keep the non-sensitive details needed to investigate, and rerun only after deciding whether the failure is transient. For reproducible application bugs, provide maintainers with a redacted minimal request and a clear expected result.
Once you know what failed, change one thing and try again. A malformed request needs a correction; an exhausted allowance needs a reset or a different permitted route; a temporary provider failure may justify a bounded retry. Keep the diagnosis that specific, and you'll avoid spending the afternoon cycling through model names.