Errori di rate limit di OpenRouter su Hermes Agent

Il tuo agente si è fermato a metà conversazione

Sei al terzo turno di una chat con Hermes Agent finalmente utile quando la risposta torna vuota, e il log mostra una riga rossa: 429 Too Many Requests. O peggio, un 402 Payment Required perché il modello ha rifiutato la richiesta di netto. L'agente che un'ora fa girava bene ora è un muro di errori di retry, e sei a una sessione di debug dal cambiare provider.

I codici di errore di OpenRouter sono precisi, una volta che sai cosa vuole dire ciascuno. 429 è un rate limit e arriva da tre posti diversi. 402 è esaurimento di credito e non si comporta per niente come un 429. 503 è indisponibilità del provider upstream ed è l'unico attorno al quale puoi automatizzare senza dolore. Ciascuno ha una correzione precisa, e l'array models di Hermes Agent trasforma la maggior parte in non-eventi.

Leggere i codici di errore di OpenRouter a colpo d'occhio

Prima di toccare la config, capisci cosa ti sta dicendo l'API. OpenRouter documenta questi codici in modo esplicito e i numeri contano.

Un 429 e un 402 sembrano uguali nel terminale ma richiedono risposte opposte. Riprovare un 402 in loop brucia solo il tuo budget di retry mentre il saldo resta a zero. Riprovare un 429 con testa è tutto il gioco.

L'altro dettaglio che vale la lettura è error.metadata.provider_code. Quando un 429 arriva dal provider upstream che serve la tua richiesta (Anthropic, DeepSeek, OpenAI, Groq), OpenRouter inoltra il codice di errore originale di quel provider in quel campo. Questo distingue un limite di piattaforma OpenRouter da un limite del tenant upstream, e le due cose vogliono correzioni diverse.

Causa 1: tetto giornaliero del piano gratuito di OpenRouter

Sintomo: ieri tutto ok, stamattina anche, e ora ogni richiesta risponde 429 anche se stai mandando pochissimo traffico. Di solito appare dopo una ventina di minuti di sessione Hermes normale.

Cosa sta succedendo: il piano gratuito di OpenRouter consente 20 richieste al minuto contro modelli gratuiti, con un tetto di 50 al giorno. Un acquisto una tantum di 10 $ in crediti alza il pavimento giornaliero da 50 a 1.000 in modo permanente. Il loop di strumenti di Hermes Agent (un turno è una chiamata API, più i retry) esaurisce una giornata da 50 richieste dentro una singola conversazione di media lunghezza.

Controlla per prima cosa: verifica che il modello nella tua config sia del piano gratuito. I modelli gratuiti su OpenRouter portano il suffisso :free nello slug (deepseek/deepseek-v4-flash:free). Se la tua riga model: finisce con :free, questo tetto si applica.

Correzione immediata: aggiungi 10 $ di crediti nel pannello di OpenRouter. Il tetto giornaliero salta a 1.000/giorno per sempre, che basta per un utente Hermes normale.

Correzione di fondo: smettila di indirizzare traffico di produzione attraverso un modello gratuito. I modelli gratuiti servono per la valutazione, non per un agente in esercizio. Passa allo stesso modello senza :free e paga la tariffa (DeepSeek V4-Flash senza suffisso costa 0,14 $/M input, quindi una giornata d'uso Hermes sono pochi centesimi). La matematica completa dei prezzi sta in il modello OpenRouter più economico per Hermes Agent.

Causa 2: rate limit del provider upstream (429 con provider_code)

Sintomo: sei su un modello a pagamento, i crediti sono in salute, eppure prendi comunque 429 quando Hermes è impegnato. Il corpo della risposta contiene error.metadata.provider_code con un valore tipo rate_limit_exceeded o insufficient_quota.

Cosa sta succedendo: OpenRouter non impone tetti duri ai modelli a pagamento, ma il provider upstream sì. Anthropic, OpenAI e DeepSeek applicano limiti per account in base al tuo tier di tenancy. Quando OpenRouter instrada la tua richiesta all'upstream, l'upstream la rifiuta e OpenRouter inoltra il rifiuto come 429.

Diagnosi:

• Leggi error.metadata.provider_code. Se dice rate_limit_exceeded, è questo il caso.
• Verifica se la richiesta è caduta su un picco (decine di turni in una finestra breve) o in regime stabile. I picchi fanno scattare i limiti al minuto, il traffico costante quelli giornalieri.
• Conferma il modello. Alcuni modelli passano da un unico provider con un tetto stretto (i modelli a marchio Anthropic via OpenRouter condividono i limiti dell'account Anthropic vero e proprio).

Correzioni:

• Rispetta l'header Retry-After della risposta. Sia su 429 che su 503, OpenRouter restituisce un Retry-After in secondi. Aspetta quel tempo prima di riprovare, poi usa backoff esponenziale con jitter se continui a prendere errori.
• Configura una catena di modelli di fallback (Causa 4 più sotto). L'array di modelli è la correzione più efficace qui, perché Hermes riprova automaticamente con il modello successivo invece di far fallire il turno.
• Se un modello specifico continua a inciampare, guarda BYOK. Portare la tua chiave Anthropic o OpenAI su OpenRouter ti dà i limiti del tuo account upstream invece di condividere il pool di OpenRouter.

Causa 3: crediti finiti a metà conversazione (402)

Sintomo: l'agente ha retto i primi 30 turni, poi ogni richiesta risponde 402 insufficient_credits. Il pannello di OpenRouter mostra un saldo di 0,00 $.

Cosa sta succedendo: OpenRouter è un saldo prepagato, non una fattura mensile. Appena il saldo tocca zero, ogni richiesta viene rifiutata con 402 finché non ricarichi. Anche gli utenti di modello gratuito vedono 402 quando l'allocazione gratuita del giorno si esaurisce (usa lo stesso codice del credito a pagamento finito, cosa che confonde ma è coerente con la doc di OpenRouter).

Correzioni:

• Attiva l'auto-topup nel pannello di OpenRouter. Imposta una soglia (per esempio aggiungi 10 $ automatici quando il saldo scende sotto 2 $). È l'unica correzione che evita i 402 in produzione.
• Metti un tetto di spesa mensile nello stesso pannello così l'auto-topup non ti fa vivere in silenzio un mese brutto.
• Se stai usando BYOK sul tier Starter di Hermify, la chiave OpenRouter è tua e il saldo è tuo da ricaricare. Hermify non anticipa crediti per te.

Non implementare retry lato client per il 402. Ogni retry è un'altra chiamata API che risponde anch'essa 402, e OpenRouter le conta contro il tuo rate limit anche se falliscono.

Causa 4: nessuna catena di fallback configurata

Sintomo: qualunque disservizio di un singolo modello in qualsiasi punto della rete di provider di OpenRouter ti mette l'agente completamente offline finché l'upstream non si riprende. Un 429 sul modello primario diventa una sessione rotta.

Cosa sta succedendo: di default, Hermes Agent manda una richiesta nominando esattamente un modello. Se quel modello è in rate limit o se tutti i suoi provider sono al massimo, OpenRouter restituisce l'errore e Hermes non ha dove instradare. Ti becchi una riga rossa nel log e il turno è perso.

La correzione è il parametro models di OpenRouter, che accetta un array di modelli in ordine di priorità. Se il primo torna errore, OpenRouter prova il successivo, poi ancora il successivo. Solo quando anche l'ultimo fallisce, l'errore torna a Hermes.

Configura una catena di 3 modelli di fallback in ~/.hermes/config.yaml. Un esempio in forma di produzione:

provider: openrouter
openrouter_api_key: sk-or-la-tua-chiave-qui
model: deepseek/deepseek-v4-pro
fallback_models:
  - anthropic/claude-haiku-4-5
  - google/gemini-2.5-flash
  - openai/gpt-4.1-mini

Questa catena ti dà un primario forte (DeepSeek V4-Pro per ragionamento pesante di strumenti), un secondario rapido e affidabile di un'altra famiglia di provider e altri due fallback su cloud diversi. Se DeepSeek è degradato, la richiesta viene instradata su Anthropic senza perdere il turno. Il post su il miglior provider di modelli per Hermes Agent approfondisce i trade-off tra famiglie di provider.

Regole pratiche per la catena:

• Scegli modelli da famiglie di provider diverse. Due modelli OpenAI cadono insieme durante un incidente OpenAI.
• Ordina per qualità prima, costo dopo. La catena scorre dall'alto verso il basso e si ferma al primo successo.
• Tienila fra 3 e 5 voci. Dieci fallback sono dieci retry sequenziali in una giornata storta, il che è peggio di un fallimento rumoroso.

Causa 5: tempeste di retry generate da Hermes stesso

Sintomo: un singolo 429 esplode in centinaia di richieste fallite nel log, ognuna peggiora il rate limit. Il pannello mostra un picco di richieste proprio quando è saltato tutto.

Cosa sta succedendo: senza backoff esponenziale, Hermes riprova subito una richiesta con rate limit, il che fa scattare di nuovo lo stesso limite, che riprova ancora. Il loop di retry trasforma un errore recuperabile in un'interruzione auto-inflitta. È la versione OpenRouter del classico stampede di rate limit lato client.

Correzioni:

• Verifica che Hermes stia rispettando Retry-After. Le versioni recenti lo fanno per default; alcuni fork datati no. Guarda la versione con hermes --version e aggiorna se sei indietro.
• Configura una coda a token bucket se stai facendo girare Hermes contro un account single-tenant. Forzare un gap minimo di 3 secondi tra richieste elimina i 429 di netto in un setup mono-utente.
• Se il loop di retry è già avvenuto, aspetta 5 minuti prima di riavviare l'agente. Il rate limiter di OpenRouter ha una finestra di riscaldamento, e i riavvii immediati allungano il blocco.

Lo stesso schema di fallimento appare in qualsiasi integrazione API ad alto volume, non solo OpenRouter. Vedi debugging e osservabilità di Hermes Agent per le convenzioni di log che rendono la cosa diagnosticabile.

Quando smettere di babysittare il provider

Ogni correzione di questo post è un piccolo aggiustamento a come è cablato lo strato dei modelli. L'array models più l'auto-topup su OpenRouter coprono il 90 % di quello che si rompe. Il resto è pazienza e il giusto trattamento di Retry-After.

Quello che brucia tempo è scoprire tutto ciò nel pomeriggio in cui il tuo agente si ferma nel mezzo di un progetto, e capire allora che il tetto gratuito è scattato, la catena di fallback non era mai stata configurata e il loop di retry ha trasformato un piccolo intoppo in un blackout di due ore. Se preferisci non imparare la tassonomia di errori di OpenRouter a suon di brutte lezioni, Hermify fa girare un Hermes Agent gestito su Telegram con la catena di fallback già cablata, una chiave OpenRouter misurata (porti la tua o usi la nostra) e un pavimento di topup che ti mantiene sopra lo zero. La tua chiave BYOK resta tua, ma smetti di essere tu quello di turno per i 429.

Inizia con Hermify e salta il postmortem della tempesta di retry.

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