Fix an error

OpenRouter free tier limit: why you get 429s and what to do

OpenRouter's free models allow 20 requests a minute and 50 a day (1,000 after $10), and extra keys add nothing. Which 429 you hit and how to keep working.

Kodelyth · The team behind kRouter

Oct 5, 2026 · Updated Oct 8, 2026

8 min read

ShareX LinkedIn Hacker News Reddit

You are a few dozen requests into an agent run on an OpenRouter free model, and every call starts coming back as HTTP 429:

Rate limit exceeded: free-models-per-day. Add 10 credits to unlock 1000 free model requests per day

Or, after only a handful of requests, this one:

{"error":{"message":"Provider returned error","code":429,"metadata":{"raw":"google/gemma-4-31b-it:free is temporarily rate-limited upstream. Please retry shortly, or add your own key to accumulate your rate limits: https://openrouter.ai/settings/integrations"}}}

Both are 429s and they have nothing to do with each other. The first is OpenRouter counting your requests and lasts until midnight UTC; the second is the provider behind one model running out of room and may clear in minutes. Which one you have decides what you do next.

The three limits behind a free-model 429

OpenRouter's limits page puts two caps on free variants -- the model IDs ending in :free -- and a 429 can also come from the provider serving the request.

1. Requests per minute: 20

Free variants are capped at 20 requests a minute. Chatting rarely gets there, but an agent sends one request per step, so a tool loop or a few parallel subagents can pass 20 inside a minute.

How to tell: it clears within a minute, and the daily counter below still has requests left. When OpenRouter itself rejects a request for a platform limit, the error response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers describing the cap you hit.

The fix: send fewer requests per minute, or give the overflow somewhere else to go.

2. Requests per day: 50, or 1,000 after $10

Under 10 credits ($10) bought all-time you get 50 free-model requests a day; at 10 or more, 1,000. Three details matter:

It counts requests, not tokens. A 100,000-token request and a two-word one count once each. Shorter prompts do not stretch it.
It is one counter for every free model. Moving from one :free model to another resets nothing.
It runs per UTC day and resets at 00:00 UTC, which may fall in the middle of your working day.

How to tell: the message says free-models-per-day (accounts past the $10 line see free-models-per-day-high-balance), X-RateLimit-Remaining is 0, and X-RateLimit-Reset points at the next 00:00 UTC as a millisecond timestamp. The same three values are copied into the error body under metadata.headers, which helps when your client only shows the body, and newer responses add a limit_source of openrouter_free_tier_daily. Or ask OpenRouter directly; this call does not touch a model:

curl -s https://openrouter.ai/api/v1/key \
  -H "Authorization: Bearer $OPENROUTER_API_KEY"

The response's free_model_daily_requests object has used, limit and remaining for the current UTC day; remaining at 0 means you are done until midnight UTC. The per-minute limit is not reported there.

The fix: wait for 00:00 UTC, send the work elsewhere, or raise the cap (below).

3. The provider behind the model is full

OpenRouter's docs warn that free variants can differ from paid ones in rate limits and availability, and a popular one fills up. Then you get the second error above: the outer message is Provider returned error, metadata.raw says the model is "temporarily rate-limited upstream", and newer responses add a limit_source of upstream_provider_shared_pool. By the time you see it, OpenRouter has already tried any other providers that serve that model.

How to tell: Provider returned error outside, "rate-limited upstream" inside, and remaining from the key check still well above zero.

The fix: a different model, right now. The same model may work again shortly; if every provider OpenRouter tried sent a retry hint, the error carries a Retry-After header. The message also suggests adding your own provider key in OpenRouter's integration settings.

One more error gets mistaken for these: a 402 on a free model. OpenRouter can return it when your account balance is negative, free models included. Adding credits until the balance is above zero clears it.

What does not work

Retrying in a loop after the daily cap. Nothing gets through before 00:00 UTC; a retry loop turns a clear error into a hang.

More API keys, or more accounts. OpenRouter's limits page is direct about it: "additional accounts or API keys will not affect your rate limits", because capacity is governed globally.

Switching to another free model after the daily cap. Same counter. Switching only helps in the third case, where one model's provider is full.

openrouter/free. This router picks a free model at random for each request, from those that support what the request needs (tools, images, structured output). That helps when one provider is saturated, but every request still lands on a free model, and OpenRouter's page for the router lists free-model rate limits among its limitations. It does not promise a way around the daily cap.

Shorter prompts. The caps count requests. Fewer requests help; smaller ones do not.

The structural fix: make OpenRouter one link in a chain

More keys cannot spread the first two caps, and the third is outside your control. What holds up is what works for every free tier: put OpenRouter in a chain, with backends after it that have their own, separate limits.

kRouter lists OpenRouter as a free-tier provider, so it can sit at the front of a fallback combo:

npm install -g @sifxprime/krouter
krouter -t

Open http://localhost:20128/dashboard, go to Providers, choose OpenRouter and add your API key from openrouter.ai/settings/keys.
Go to Combos, click Create Combo and give it a name.
Click Add Model. OpenRouter's group in the picker lists its zero-price models with a context window of 200,000 tokens or more. Pick one whose ID ends in :free, then add entries from other providers.

Combo: free-first
  1. openrouter/google/gemma-4-31b-it:free   OpenRouter free model
  2. mmf/mimo-auto                           MiMo Code Free, no sign-in
  3. ds/deepseek-v4-flash                    cheap metered key: the backstop

These IDs are examples. OpenRouter's free list is short and changes often (its models API listed 16 :free entries when this was written), so pick from the picker, and for an agent, one that supports tool calls. The paid last entry makes the chain hold all day, since every free entry can run out. A local model is the other backstop with no daily cap; see running Ollama first with a cloud fallback.

Then point any OpenAI-compatible client at it and use free-first as the model name. For a client that reads the OpenAI SDK's environment variables:

export OPENAI_BASE_URL=http://localhost:20128/v1
export OPENAI_API_KEY=<key from the dashboard's Endpoint page>

Requests from the same machine need no key unless you set REQUIRE_API_KEY=true. Two choices make the chain easier on OpenRouter's limits:

Round-robin for the free entries. Set on a combo's card, it rotates which entry goes first, one request each by default. Put OpenRouter and MiMo in a round-robin combo of their own and OpenRouter goes first on every other request, so while MiMo is answering, the 50 last about twice as long and a burst puts about half its requests on OpenRouter. Make that combo the first entry of a fallback combo, so the paid backstop is still tried last; round-robin on the three-entry combo above would hand it a third of all requests.
One OpenRouter free model per combo. A second only helps when a provider is saturated; after the daily cap, each OpenRouter entry fails in turn before the chain moves on.

What kRouter does with each 429

When the OpenRouter entry fails, kRouter cools that model down on that connection and moves to the next entry, so the request that hit the limit is still answered.

Since v0.5.164, kRouter tells the three apart:

Daily cap. kRouter parks that model on that connection until the reset OpenRouter names in the error (or 00:00 UTC if it names none) and answers from the next entry straight away. Paid models on the same key keep working. The connection's last error on the OpenRouter provider page says the free-model daily limit was reached and when it resets.
Per-minute cap, or a saturated provider. kRouter skips that model for about 90 seconds. A per-minute window has cleared by then, and a saturated provider gets another try after a short wait instead of being parked for hours.

Versions before 0.5.164 read every one of these as a per-minute limit, including the daily cap, so they made one quick failed attempt at OpenRouter about every 90 seconds until midnight UTC (you lost a round trip, not the request) and the last error wrongly called the daily quota healthy. Update if you rely on OpenRouter's free models.

Each cooldown shows up on the dashboard's Console Log page as an [AUTH] line naming the locked model and the number of seconds.

When paying $10 is worth it

Buying $10 of OpenRouter credits once raises the free-model cap from 50 to 1,000 requests a day. The details:

The tier follows credits purchased all-time, not your balance. Free models cost nothing per token, and spending the credits on paid models does not drop you back to 50.
The line sits at 9 credits in practice. OpenRouter grants the higher ceiling from one credit below 10, to absorb rounding and top-up fees.
Keep the balance above zero. A negative balance can produce 402 errors on free models too.
It does nothing for the third case. Credits do not add room at a saturated provider.

The other paid option is the model without :free on the end, where one exists: OpenRouter says paid variants have no platform-level request cap, and you pay per token instead.

If OpenRouter's free models are your main backend and you hit 50 most days, pay the $10 once. If other links in your chain absorb the overflow, you may never need it.

Working out which limit you hit

What you see	Limit	What to do
`free-models-per-day`, `remaining` at 0	Daily cap: 50, or 1,000 after $10	Route elsewhere until 00:00 UTC, or buy $10 of credits
Clears within a minute, `remaining` above zero	20 requests a minute	Fewer parallel requests, or round-robin with another backend
`Provider returned error`, "temporarily rate-limited upstream"	The provider behind that model is full	Switch model now, retry it later
402 on a free model	Negative balance	Add credits until the balance is above zero

Common questions

When does the OpenRouter free limit reset?

The daily counter resets at 00:00 UTC and the per-minute limit within a minute. A provider-side 429 has no fixed reset: it lasts as long as that provider is saturated, which is why switching model beats waiting.

Does a second API key or a second account give me more free requests?

No. OpenRouter says additional accounts or API keys do not change your rate limits, because it governs capacity globally. A router rotating several OpenRouter keys gains nothing on the free tier either.

Is the $10 used up when I call free models?

No. Free models cost nothing per token, and the 1,000-a-day tier follows credits purchased all-time, so spending them on paid models keeps the higher cap. Just keep the balance above zero.

Why do I get a 429 after only a few requests?

Usually the provider serving that free model is saturated ("temporarily rate-limited upstream" in the metadata), or an agent burst past 20 requests a minute. If free_model_daily_requests.remaining at /api/v1/key is well above zero, it is not the daily cap.

Does kRouter know when OpenRouter's daily cap resets?

Yes, from v0.5.164. It reads the reset from the error (or uses 00:00 UTC) and parks only that model on that connection until then. Earlier versions treated the daily cap as a per-minute limit and retried about every 90 seconds until midnight.