Hermes Agent rate limits and provider errors

What you see

Replies stop with a 429 or rate-limit message, a billing or quota error (402), an auth error (401/403), 'model not found', an HTTP 400 on first run, or a message like 'Could not open a stream to <host> after N attempts'. In messaging apps you may see 'interrupted mid-request' or 'not running or is unreachable'.

Likely causes

These errors come from your model provider, not from Hermes itself, and the status code is the best clue. Some are temporary and worth retrying, some mean you need a different key or more credit, and some will never succeed no matter how often you retry. Hermes treats them differently for that reason, so it helps to know which one you're looking at.

• 429: you hit the provider's request or token limits.
• 402 or daily quota: billing, credits or plan caps.
• 401/403: wrong, expired or mismatched API key, or an OAuth login that needs refreshing.
• 400 on first run: usually a model name mismatch or no access to that model; on OpenRouter it can also mean you need credits.
• Stream errors: a wrong base_url, a local server that isn't running, or an endpoint rejecting a very large request.
• A policy refusal from the provider account itself, which retrying won't fix.

Check this first

• /status: which model and provider actually answered.
• hermes config show | head -20, then hermes model to confirm provider and model name.
• hermes chat -q "hello" --model <a known-good model> to separate a model problem from a config problem.
• hermes auth list <provider>: which credential is active and whether any are cooling down.
• logs/agent.log in your Hermes home for the raw error.
• hermes doctor if errors persist.

Fix

Hermes already retries before giving up (agent.api_max_retries defaults to 3), and rate-limit waits that name a reset time are capped at 600 seconds per retry. Beyond that:

• Occasional 429s: wait and retry with /retry, or switch model with /model.
• Sustained 429s: add more keys to a credential pool with hermes auth add <provider>. On a 429 Hermes retries the same key once, then rotates; 402s rotate immediately. Choose a rotation strategy under credential_pool_strategies (fill_first, round_robin, least_used or random).
• Provider-wide outages: add a fallback with hermes fallback add, which writes fallback_providers in config.yaml. Each entry needs a provider and a model. Fallback triggers after retries on 429 and 5xx errors, and immediately on 401, 403 and 404.
• Key problems: re-run hermes model, or hermes config set OPENROUTER_API_KEY <key> (or your provider's variable), and check ~/.hermes/.env for conflicting keys.
• Model not found: pick a valid name from hermes model and set model.default, or use hermes chat --model <name> for one session.
• Large-request stream errors: run /compress, or raise the endpoint's request size limit.
• Cooldowns stuck after you fixed billing: hermes auth reset <provider>.

If it still fails

Remember that fallback is turn-scoped: each new message starts on the primary again, and fallback fires at most once per turn. If the primary keeps failing you'll bounce every turn, and each switch invalidates the prompt cache, which costs money. In that case switch the default model rather than relying on fallback. Cron jobs pinned to their own provider or model don't fall back at all, so check those separately. For account policy refusals, contact the provider or move to another one.

Related guides

• Hermes Agent still using the wrong model
• How to keep Hermes Agent costs down
• How to choose a model for Hermes Agent

Spotted something wrong or out of date? Tell us on X at @HermesWatcher↗ (opens in a new tab) and we will fix it.

New Hermes Agent updates every day on X. Follow @HermesWatcher