OpenRouter Rate Limit Errors on Hermes Agent: Fixes

Your Agent Stopped Mid-Conversation

You are three turns into an actual useful chat with Hermes Agent when the reply comes back empty, and the log shows a red line: 429 Too Many Requests. Or worse, a 402 Payment Required that says the model refused the request outright. The agent that was fine an hour ago is now a wall of retry errors and you are one debugging session away from switching providers.

OpenRouter's error codes are precise once you know what each one means. 429 is a rate limit and comes from three different places. 402 is credit exhaustion and behaves nothing like 429. 503 is upstream provider unavailability and is the one you can automate around. Every one of them has a specific fix, and Hermes Agent's models array turns most of them into a non-event.

Reading OpenRouter Error Codes at a Glance

Before you touch config, know what the API is actually telling you. OpenRouter documents these codes explicitly and the numbers matter.

A 429 and a 402 look similar in a terminal but call for opposite responses. Retrying a 402 in a loop just burns your retry budget while the credit balance stays at zero. Retrying a 429 sensibly is the whole game.

The other detail worth reading is error.metadata.provider_code. When a 429 originates from the upstream provider serving your request (Anthropic, DeepSeek, OpenAI, Groq), OpenRouter forwards the provider's original error code in that field. That distinguishes an OpenRouter platform limit from an upstream tenant limit, and the two have different fixes.

Cause 1: OpenRouter Free-Tier Daily Cap

Symptom: everything worked yesterday, everything worked this morning, and now every request returns 429 even though you are barely sending traffic. Usually appears after about 20 minutes of a normal Hermes session.

What is happening: OpenRouter's free tier allows 20 requests per minute against free models, capped at 50 requests per day. A one-time purchase of $10 in credits raises the daily floor from 50 to 1,000 permanently. Hermes Agent's chatty tool loop (one turn is one API call, plus retries) exhausts a 50-request day inside a single medium-sized conversation.

Check first: confirm the model in your config is on the free tier. Free models on OpenRouter carry a :free suffix in their slug (deepseek/deepseek-v4-flash:free). If your model: line ends in :free, this cap applies.

Fix, immediate: add $10 of credits on the OpenRouter dashboard. The daily cap jumps to 1,000/day forever, which is enough for a normal Hermes user.

Fix, structural: stop routing production Hermes traffic through a free model. Free models are for evaluation, not for a running agent. Swap to the same model without :free and pay the going rate (DeepSeek V4-Flash without the suffix is $0.14/M input, so a day of Hermes usage is single-digit cents). The full pricing math is in the cheapest OpenRouter model for Hermes Agent.

Cause 2: Upstream Provider Rate Limit (429 with provider_code)

Symptom: you are on a paid model, credits are healthy, but you still get 429 when Hermes is busy. The response body contains error.metadata.provider_code with a value like rate_limit_exceeded or insufficient_quota.

What is happening: OpenRouter itself does not hard-cap paid models, but the upstream provider does. Anthropic, OpenAI, and DeepSeek each apply per-account rate limits based on your tenancy tier. When OpenRouter routes your request to the upstream, the upstream refuses, and OpenRouter forwards that refusal as a 429.

Diagnostics:

• Read error.metadata.provider_code. If it says rate_limit_exceeded, this is the case.
• Check whether the request hit at a burst (dozens of turns in a short window) or steady-state. Bursts trip per-minute limits, steady traffic trips per-day.
• Confirm the model. Some models route through a single provider with a tight cap (Anthropic-branded models via OpenRouter share Anthropic's own account limits).

Fixes:

• Honor the Retry-After response header. On both 429 and 503, OpenRouter returns a Retry-After value in seconds. Wait that long before retrying, then use exponential backoff with jitter if you still get errors.
• Configure a fallback model chain (Cause 4 below). The models array is the single most effective fix here because Hermes automatically retries with the next model instead of failing the turn.
• If one specific model keeps tripping, look at BYOK. Bringing your own Anthropic or OpenAI key to OpenRouter gives you the rate limits of your own upstream account rather than sharing OpenRouter's pool.

Cause 3: Credits Ran Out Mid-Conversation (402)

Symptom: the agent worked for the first 30 turns, then every request returns 402 insufficient_credits. The OpenRouter dashboard shows a balance of $0.00.

What is happening: OpenRouter is a prepaid balance, not a monthly invoice. Once the balance hits zero, every request is refused with 402 until you top up. Free-model users also see 402 when the daily free allowance is exhausted (it uses the same code as paid credit exhaustion, which is confusing but consistent with OpenRouter's docs).

Fixes:

• Enable auto-topup on the OpenRouter dashboard. Set a threshold (e.g. auto-add $10 when balance drops below $2). This is the single fix that prevents 402s in production.
• Set a monthly spending cap on the same dashboard so auto-topup cannot silently balloon into a bad month.
• If you are using BYOK on Hermify's Starter tier, the OpenRouter key is yours and the balance is yours to top up. Hermify does not proxy credits on your behalf.

Do not implement client-side retries for 402. Every retry is another API call that also returns 402, and OpenRouter counts those against your rate limit even though they fail.

Cause 4: No Fallback Chain Configured

Symptom: any single-model outage anywhere in the OpenRouter provider network takes your agent completely offline until the upstream recovers. One 429 on the primary model becomes a broken session.

What is happening: by default, Hermes Agent sends a request naming exactly one model. If that model is rate limited or if all its providers are at capacity, OpenRouter returns the error and Hermes has nowhere to route. You get a red log line and the turn is lost.

The fix is OpenRouter's models parameter, which takes an array of models in priority order. If the first model returns an error, OpenRouter tries the next one, then the next. Only when the last one also fails does the error come back to Hermes.

Configure a 3-model fallback chain in ~/.hermes/config.yaml. A production-shaped example:

provider: openrouter
openrouter_api_key: sk-or-your-key-here
model: deepseek/deepseek-v4-pro
fallback_models:
  - anthropic/claude-haiku-4-5
  - google/gemini-2.5-flash
  - openai/gpt-4.1-mini

That chain gives you a strong primary (DeepSeek V4-Pro for tool-heavy reasoning), a fast reliable secondary from a different provider family, and two more fallbacks in different clouds. If DeepSeek is degraded, the request routes to Anthropic without dropping the turn. The best model provider for Hermes Agent post has more on the tradeoffs between provider families.

Rules of thumb for the chain:

• Pick models from different provider families. Two OpenAI models fail together during an OpenAI incident.
• Order by quality first, cost second. The chain runs top-down and stops at the first success.
• Keep it to 3-5 entries. Ten fallbacks means ten sequential retries on a bad day, which is worse than one loud failure.

Cause 5: Retry Storms From Hermes Itself

Symptom: a single 429 cascades into hundreds of failed requests in the log, each one making the rate limit worse. The dashboard shows a request spike right when things broke.

What is happening: without exponential backoff, Hermes retries a rate-limited request immediately, which trips the same rate limit again, which retries again. The retry loop turns one recoverable error into a self-inflicted outage. This is the OpenRouter version of a classic client-side rate-limit stampede.

Fixes:

• Verify Hermes is honoring Retry-After. Modern versions do this by default; older forks may not. Check the version with hermes --version and update if you are behind.
• Configure a token-bucket queue if you are running Hermes against a single-tenant account. Enforce a minimum 3-second gap between requests, which eliminates 429s entirely for a single-user setup.
• If the retry loop already happened, wait 5 minutes before restarting the agent. OpenRouter's rate limiter has a warm-up window and immediate restarts extend the ban.

The same failure pattern shows up on any high-volume API integration, not just OpenRouter. See Hermes Agent debugging and observability for the log-reading conventions that make this diagnosable.

When to Stop Babysitting the Provider

Every fix in this post is a small correction to how the model layer is wired. The models array plus auto-topup on OpenRouter cover 90% of what breaks. The rest is patience and the right Retry-After handling.

What burns time is discovering all of this the afternoon your agent stops working mid-project, then realizing the free-tier cap kicked in, the fallback chain was never configured, and the retry loop turned a small hiccup into a two-hour outage. If you would rather not learn OpenRouter's error taxonomy the hard way, Hermify runs a managed Hermes Agent on Telegram with the fallback chain pre-wired, a metered OpenRouter key you can bring or use ours, and a topup floor that keeps you above zero. Your BYOK key is still yours, but you stop being the one on call for 429.

Get started with Hermify and skip the retry-storm postmortem.

Sources

• OpenRouter API credit and rate limits
• OpenRouter model fallbacks documentation
• OpenRouter reliability and failover explainer
• OpenRouter free tier 2026 breakdown
• Handling OpenRouter 429 with retry strategies