Hermes credential "cooling down" after a 429: hermes auth reset
Hermes Agent benched a provider credential after a 429 and says it resets in hours or days. Why it lasts that long, how to see it, and how to clear it.
Hermes Agent benches a credential after the provider refuses it with a 429 (or a 402), and stops using it until a reset time. By default that is an hour, or a minute when it is your only credential, but when the provider names its own reset time Hermes uses that instead, which can be days away. If the provider’s limit has already reset and Hermes is still refusing, clear the bench with hermes auth reset <provider>, for example hermes auth reset openai-codex. A running gateway picks the reset up on its next request, so it does not need a restart. If the limit has not reset, the next request is refused again and the credential goes back on the bench.
The message, and why it does not name the fix
In Hermes’s source on its main branch and in v0.23.1 (November 2026), a provider whose every credential is benched prints, in one of two forms:
Provider 'openai-codex' is set in config.yaml but its only credential is cooling down after a rate limit / quota error (429); the next one resets at 2026-11-21 09:00 UTC. Wait for the reset, add another credential with `hermes auth add openai-codex`, or switch to a different provider with `hermes model`.
With several credentials, “its only credential is” becomes “all 3 credentials are”, and the time is the earliest of their resets. That time is printed in the machine’s own timezone with its abbreviation, so on a server set to UTC it says UTC. The wording is in Hermes’s source; it offers waiting, another credential or another provider, and leaves out the command that lifts the bench. In an open issue collecting the reports, users describe meeting the state as “no credentials found”, as a /model picker with the provider missing, or as a scheduled job that blocks, and one Docker user on a ChatGPT plan saw “HTTP 429: The usage limit has been reached” for days after the plan’s limit had reset, with a cooldown of 324,883 seconds, nearly four days.
A different message means the provider says you are out of money rather than out of requests: “Provider … is out of usable credentials: its only credential is exhausted”, ending “Add credits or update billing with that provider, then retry”. That one is settled at the provider, and a reset in Hermes only brings the same refusal back.
How long the bench lasts
Each credential Hermes holds for a provider is an entry in a pool, and the pool decides when an entry may be used again. Nous’s credential pools page gives the defaults:
- 429 rate limit: “Retry same key once (transient). Second consecutive 429 rotates to next key”, and the key is benched for 1 hour. A ChatGPT plan’s usage limit skips the retry, because “the cap won’t clear on retry”.
- 402 billing or quota: rotate at once, benched for 1 hour.
- 401 sign-in expired: Hermes tries to refresh the sign-in first, and benches the key for 5 minutes if that fails.
Two things change those numbers. In the pool’s source, a credential that is the only one left to try is benched for 60 seconds instead of an hour after a rate limit, since an hour would mean an hour of failures; a billing refusal keeps the full hour. And, in the docs’ words, “Provider-supplied reset_at timestamps override these default cooldowns.” When the refusal carries a reset time, or a message Hermes can read a delay from, the bench lasts until that time, and the code sets no upper limit on it. A plan whose weekly allowance is spent can name a reset several days out, which is how a single 429 turns into a bench of days. For what a ChatGPT plan’s refusal says on its own, see what “You’ve hit your usage limit” means in Codex.
As a rule, while a credential is benched Hermes does not ask the provider again. One of its Anthropic messages says so outright: “Until that cooldown clears, this error can be replayed from cache without contacting the API.” So a limit that the provider lifts early, or a reset time that was wrong, is invisible to Hermes until the bench runs out or is cleared.
See the state, then clear it
The pool lives in ~/.hermes/auth.json, under its credential_pool key, next to the sign-ins themselves, so read it through Hermes rather than opening the file:
hermes auth list openai-codexCopiedEach credential is a numbered row with its label, type and source. A benched one ends with rate-limited and the HTTP code, followed by the time left, such as (3d 18h left), or (ready to retry) once that time has passed. A row marked auth failed with “(re-auth may be required)” is a sign-in problem, not a limit, and is fixed by signing in again with hermes auth add <provider>.
To lift the bench on every credential of the provider, or on one, by its number, id or label:
hermes auth reset openai-codex
hermes auth reset openai-codex 2CopiedIt prints “Reset status on 1 openai-codex credentials” (or the one credential’s number and label). The provider names are the ones Hermes uses in config.yaml and in the message: openai-codex for a ChatGPT plan, anthropic, openrouter and so on.
A reset does not touch the provider. If its limit is still in force, the next request is refused and the credential is benched again, with a fresh reset time. Hermes’s own source says the same of the neighbouring hermes auth refresh <provider>, which renews a sign-in and also lifts its bench: “It proves the grant is alive, not that the provider’s quota is back: if the account is still capped, the next request 429s and benches it again.” So check the provider’s own usage page first; resetting before the limit has reset only moves the failure to the next request.
On a server: the gateway, Docker and scheduled jobs
The gateway that keeps Hermes on Telegram, Discord and the rest does not need restarting after a reset. The credential pools page says the reset “applies to running sessions too: a live gateway or chat picks the reset up on its next request”, and v0.23.1’s pool code honours a reset run from another process. Run it as the user whose ~/.hermes the gateway uses, so that both read the same pool; for a gateway set up as a systemd user service, as in installing Hermes Agent on a Linux server, that is the account that installed it.
In Docker, Hermes’s data is the container’s /opt/data volume, and the command runs inside the container, as Nous’s Docker page does for its other commands. With the container named hermes:
docker exec hermes hermes auth list openai-codex
docker exec hermes hermes auth reset openai-codexCopiedScheduled jobs are where the bench costs most, because nobody sees the first refusal: with no fallback configured, every job after it fails against the same benched credential until the reset time. If jobs have stopped answering, hermes auth list is the first thing to run. Two settings keep work going while a provider is benched, and neither gets round the provider’s limit: when every credential in the pool is benched, Hermes falls through to a fallback model if one is configured (hermes fallback manages the providers it tries), and a provider you pay per token, such as an API key, is not bound by a plan’s five-hour or weekly window. If the plan in question is a Claude subscription, check first what Hermes can use it for at all: using a Claude subscription in Hermes, Pi and OpenCode covers it.
A bench that only a reset clears
One refusal is benched with no end time at all. When a ChatGPT plan does not include a model, the provider answers “The ‘<model>’ model is not supported when using Codex with a ChatGPT account.” Hermes then benches that credential for that model only, and the docs give its length as “Until hermes auth reset (per model; an entitlement is a plan property, not a window)”. Other models keep using the credential. Pick a model the plan includes; the reset is for after the plan has changed.