OpenRouter 429 rate limit: free-model caps and upstream limits
OpenRouter's 429 is one of three limits: the free models' daily cap, their per-minute cap, or the provider's. How to tell which, and what clears each.
A 429 from OpenRouter is one of three limits, and the message says which. “Rate limit exceeded: free-models-per-day” is the daily cap on :free models: 50 requests per UTC day until your account has bought 10 credits in total, 1,000 after; retrying does nothing until the day turns. Free models also allow 20 requests a minute, a cap that clears within the minute. “<model> is temporarily rate-limited upstream” means the provider serving that model is throttling everyone on it, not you: wait the Retry-After it sends, use another model, or add your own provider key in OpenRouter. GET /api/v1/key shows how many free requests are left today.
Telling the three apart
- The free models’ daily cap. The message names it: “Rate limit exceeded: free-models-per-day. Add 10 credits to unlock 1000 free model requests per day” on an account below the threshold, as reported in 2025, and “Rate limit exceeded: free-models-per-day-high-balance.” on one above it, in an OpenClaw report of September 2026. It only hits model IDs ending in
:free. - The free models’ per-minute cap. 20 requests a minute on
:freemodels, for every account whatever it has bought. OpenRouter’s documented body for its own 429 carries just “Rate limit exceeded” and anerror_typeofrate_limit_exceeded. - The provider’s limit. “is temporarily rate-limited upstream”, usually wrapped as “429 Provider returned error” with the sentence inside
error.metadata.raw. Paid models get it too: one OpenCode report has “deepseek/deepseek-v4-pro is temporarily rate-limited upstream.”
OpenRouter’s limits reference gives one more tell: a 429 from its own free-model limits carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. Most agents do not print headers, so the message text in the agent’s log is the practical check. If the 429 arrives after a reply has started streaming, it comes inside the stream with finish_reason: "error" and an HTTP 200, which some tools read as an empty answer rather than a rate limit.
The free models’ limits, and what 10 credits changes
As of November 2026, the limits on :free variants are:
Credits bought, all time Per minute Per day
Less than 10 20 50
At least 10 20 1,000CopiedThree details in the docs matter here. The tier is chosen by credits bought over the account’s life, not the current balance, so a one-time purchase of 10 credits raises the daily cap for good, even once the balance has been spent. The per-minute cap does not move at all. And a negative balance blocks free models too: OpenRouter says adding credits to put the balance above zero is what lets you use them again. The daily count is per UTC day, which on a machine set to another timezone does not end at your midnight. Requests sent with your own provider key through OpenRouter are not counted against the daily cap.
An agent spends requests faster than a person typing. Every round trip of a task, each tool call and its result, is a request, so 50 a day can be one afternoon’s small task. Subagents or parallel tool calls running at once also meet the 20-a-minute cap sooner than one conversation does.
How many free requests are left today
Ask OpenRouter about the key, from the machine the agent runs on and with the variable it reads:
curl https://openrouter.ai/api/v1/key \
-H "Authorization: Bearer $OPENROUTER_API_KEY"CopiedThe response does not print the key. In data.free_model_daily_requests, per the endpoint’s reference, used and remaining are the account’s free-model requests in the current UTC day, and limit is 50 or 1,000 depending on credits bought. Read the limit rather than is_free_tier, which the docs say does not decide the tier, and ignore rate_limit, a legacy field. The per-minute cap is not reported here. A remaining of 0 means every :free request on the account fails until the UTC day turns, whichever key sends it.
“Temporarily rate-limited upstream”
This one is not about your account. The provider running the model has refused OpenRouter, and in the body below limit_source says so: upstream_provider_shared_pool, the provider’s capacity shared by everyone sending to that model through OpenRouter. A full body, from a Hermes report in September 2026, shortened:
{"error": {"message": "Provider returned error", "code": 429,
"metadata": {
"raw": "minimax/minimax-m3:free is temporarily rate-limited
upstream. Please retry shortly, or add your own key to
accumulate your rate limits:
https://openrouter.ai/settings/integrations",
"provider_name": "GMICloud",
"limit_source": "upstream_provider_shared_pool",
"retry_after_seconds": 60,
"headers": {"Retry-After": "60"}}}}CopiedBy the time you see it, OpenRouter has already tried the model’s other providers: its docs say fallback routing does that before the error reaches you. Buying credits does not change it, since the limit is the provider’s. What does:
- Waiting the
Retry-After. It is in the body and the header; 60 seconds in that report. OpenRouter’s docs ask clients to honour it. - Another model. A fallback model in your agent’s settings keeps it answering while one model is throttled. The same model without
:freeis a separate listing at the paid price; whether its providers have room at that moment is for its own endpoint list to say. - Your own provider key. The message’s own suggestion: a key you add under OpenRouter’s integrations settings is billed and limited on your account at that provider, not the shared pool.
Agents show it in different ways. Hermes retried three times and then printed only “API call failed after 3 retries: HTTP 429: Provider returned error”, without the sentence that explains it; that issue was still open in November 2026. An OpenCode user filed the DeepSeek case as “DeepSeek v4 pro hanging”, and a maintainer answered “This is just openrouter ratelimits not an opencode issue.” An agent that seems stuck on an OpenRouter model may simply be waiting out these refusals. How to dig the inner message out of an agent that shows only the wrapper is in the “Provider returned error” guide.
When the agent misreads the daily cap
The daily cap is the one 429 that a retry cannot clear, and agents have handled it badly in both directions.
- Retrying it as if it would pass. In OpenClaw 2026.9.4, the rate-limit classifier did not recognise “per-day” with a hyphen, treated the cap as a short limit and kept retrying the same model instead of moving to a fallback: one day’s log had 455 of these 429s and 385 same-model retries, all after the cap was reached. The issue was closed as fixed on September 16, 2026; on an older install, update, and look for the message repeating in the Gateway log.
- Giving up on everything on the key. A Hermes user reported in October 2026 that the free daily cap benched the whole OpenRouter credential, so fallbacks were skipped with “credential pool is exhausted (every entry in cooldown)”, a paid model on the same key included, and the bench survived restarts. Hermes’s credential pool docs give
hermes auth reset openrouterto “Clear all cooldowns/exhaustion status”. That lets the paid model run again; the free model keeps refusing until the UTC day turns.
A 402 that behaves like a rate limit
This request would exceed your available credits given your
current in-flight requests.CopiedThis is HTTP 402, not 429, but it is a limit on concurrency rather than an empty balance. On some prepaid accounts, OpenRouter holds each running request’s estimated cost against the account, and the total held at once may not exceed what the docs call the in-flight spending budget, “a fraction of your current credit balance, up to a fixed ceiling.” Several requests running at once on a modest balance, parallel subagents for instance, can fill it while the balance still covers each one. It carries a Retry-After, and the errors reference says a 402 is a wait-and-retry case only when limit_source is openrouter_in_flight_budget, adding that no SDK retries a 402 on its own. Free models, and requests made wholly on your own provider key, are outside it.
Agents tend to file it under billing. In a Hermes report from September 2026, a body that read “Retry after in-flight requests settle, or add credits.” with Retry-After: 120 was logged as “Non-retryable client error (HTTP 402). Aborting.”, and a scheduled job failed on three days running. Fewer requests at once, or more balance, makes room. When a single request’s estimate is larger than the whole budget, the docs say retrying will not help, and the fix is the request’s output ceiling: that arithmetic is in “requires more credits, or fewer max_tokens”. A 403 naming a key or budget limit is a spending cap instead, covered in “Key limit exceeded”.
On a server nobody is watching
Free models and an always-on agent are a poor fit for the daily cap. OpenClaw’s proactive check, where an agent has one, runs every 30 minutes by default, 48 times a day; on a :free model with the 50-request cap, those checks alone leave almost nothing for the work you ask of it, and the heartbeat guide covers what it spends and how to cut it. Scheduled jobs late in the UTC day meet a cap already spent by the day’s use, and recover only after 00:00 UTC.
Before leaving an agent on OpenRouter unattended, decide what it should do on each kind of refusal: a per-minute or upstream 429 is worth a wait and a retry, the daily cap is worth a switch to a paid or own-key model, and nothing about any of them is worth a tight retry loop. Then check, in the agent’s log after a quiet night, that it did what you meant: the message text tells you which limit it met.