Hermes "API call failed after 3 retries: Connection error."
"API call failed after 3 retries" is a catch-all, not one bug. Hermes prints it for provider safety blocks, SSL/connection drops, 429 rate limits, 402 billing errors, and retired model ids alike. Check the Hermes logs for the real HTTP status, verify your model id still exists, confirm provider credit, and configure fallback providers so one upstream failure doesn't end the request.
Likely cause
This is a catch-all message, which is why it is so hard to act on. Hermes prints the same line for at least four unrelated failures: a provider safety/moderation block on your content, a genuine transport error (SSL drops, connection reset by peer), a rate-limit or billing response (429 or 402), and a model that no longer exists on your plan. Issue #18028 tracks exactly this — the request to classify these as provider_safety_block, provider_connection_error, tool_error and gateway_delivery_error instead of one generic string. There is also a config-shaped variant: Hermes v0.16.0 on Linux pipx installs sent an empty runtime model and provider, so every call failed instantly with retries exhausted (issue #48061).
The fix
- 1 Read the Hermes logs rather than the CLI message. The real HTTP status (404, 429, 402, 503) is recorded there and tells you which of the four causes you have.
- 2 Confirm your configured model id still exists and is spelled exactly as the provider lists it. A retired or renamed model produces this error, and retrying can never fix it.
- 3 Check the provider dashboard for remaining credit and rate-limit status — a 402 billing response and a 429 rate limit both surface as this same message.
- 4 If you installed with pipx on Linux, check `hermes --version` and upgrade past v0.16.0, which shipped an empty runtime model/provider bug.
- 5 Configure fallback providers so a single upstream failure rolls over to a second provider instead of burning three retries and stopping.
hermes --versionHit a different error?
Paste any agent error and get the cause and fix in seconds.
Frequently asked questions
Will waiting and retrying fix it?
Only if the cause was transient — a connection drop or a temporary rate limit. If the cause is a retired model id, a billing failure, or a safety block, retrying will fail identically every time.
Why does the message always say 'Connection error' even when it isn't one?
Hermes collapses several distinct failure classes into one message. Issue #18028 is the open request to classify them properly. Until that lands, the logs are the only reliable source.
Does this mean my API key is bad?
Not necessarily. A valid key with no remaining credit produces the same error as an invalid one. Check the billing page before regenerating the key.
Stop firefighting agent errors
Decoding errors one at a time is the manual version of what BetterClaw automates. Run your OpenClaw agents hosted with managed models, retries and config validation built in.
Free plan available · Pro $49/mo · BYOK · 7-day money-back guarantee