Erreurs de rate limit OpenRouter sur Hermes Agent

Votre agent s'est arrêté en plein milieu

Vous en êtes au troisième échange d'une conversation Hermes Agent enfin utile quand la réponse revient vide, et le log affiche une ligne rouge : 429 Too Many Requests. Ou pire, un 402 Payment Required parce que le modèle a refusé la requête d'entrée de jeu. L'agent qui roulait il y a une heure est maintenant un mur d'erreurs de retry, et vous êtes à une session de debug de changer de fournisseur.

Les codes d'erreur d'OpenRouter sont précis dès qu'on sait ce que chacun veut dire. 429 est un rate limit et vient de trois endroits différents. 402 est un épuisement de crédit et ne se comporte en rien comme un 429. 503 est une indisponibilité du fournisseur upstream et c'est le seul autour duquel on peut automatiser sans douleur. Chacun a un correctif précis, et le tableau models de Hermes Agent transforme la plupart en non-événements.

Lire les codes d'erreur OpenRouter d'un coup d'œil

Avant de toucher à la config, comprenez ce que l'API vous dit. OpenRouter documente ces codes de façon explicite, et les numéros comptent.

Un 429 et un 402 se ressemblent dans un terminal mais appellent des réponses opposées. Retenter un 402 en boucle brûle votre budget de retry pendant que le solde reste à zéro. Retenter un 429 avec méthode, c'est tout le jeu.

L'autre détail qui vaut la lecture est error.metadata.provider_code. Quand un 429 vient du fournisseur upstream qui sert votre requête (Anthropic, DeepSeek, OpenAI, Groq), OpenRouter transmet le code d'erreur original de ce fournisseur dans ce champ. Cela distingue un plafond de plateforme OpenRouter d'un plafond de tenant upstream, et les deux ont des correctifs différents.

Cause 1 : plafond quotidien du palier gratuit d'OpenRouter

Symptôme : hier ça marchait, ce matin aussi, et maintenant chaque requête renvoie 429 alors que vous n'envoyez quasi rien. Apparaît en général après une vingtaine de minutes de session Hermes normale.

Ce qui se passe : le palier gratuit d'OpenRouter autorise 20 requêtes par minute sur les modèles gratuits, plafonnées à 50 par jour. Un achat unique de 10 $ de crédits fait passer le plancher quotidien de 50 à 1 000 pour toujours. La boucle d'outils de Hermes Agent (un tour est un appel API, plus les retries) épuise un jour à 50 requêtes en une seule conversation moyenne.

Vérifiez en premier : confirmez que le modèle dans votre config est du palier gratuit. Les modèles gratuits sur OpenRouter portent le suffixe :free dans leur slug (deepseek/deepseek-v4-flash:free). Si votre ligne model: finit par :free, ce plafond s'applique.

Correctif immédiat : ajoutez 10 $ de crédits sur le tableau de bord OpenRouter. Le plafond quotidien passe à 1 000/jour à vie, ce qui suffit à un utilisateur Hermes normal.

Correctif structurel : arrêtez de router du trafic de production via un modèle gratuit. Les modèles gratuits servent à évaluer, pas à faire tourner un agent. Passez au même modèle sans :free et payez le tarif (DeepSeek V4-Flash sans suffixe coûte 0,14 $/M input, donc une journée d'usage Hermes fait quelques centimes). Les maths complètes sont dans le modèle OpenRouter le moins cher pour Hermes Agent.

Cause 2 : rate limit du fournisseur upstream (429 avec provider_code)

Symptôme : vous êtes sur un modèle payant, les crédits sont sains, mais vous prenez quand même un 429 quand Hermes travaille. Le corps de la réponse contient error.metadata.provider_code avec une valeur du type rate_limit_exceeded ou insufficient_quota.

Ce qui se passe : OpenRouter n'impose pas de plafond dur sur les modèles payants, mais le fournisseur upstream, si. Anthropic, OpenAI et DeepSeek appliquent des limites par compte selon votre tier. Quand OpenRouter route votre requête vers l'upstream, l'upstream refuse et OpenRouter renvoie ce refus sous forme de 429.

Diagnostic :

• Lisez error.metadata.provider_code. S'il dit rate_limit_exceeded, c'est ce cas.
• Vérifiez si la requête est tombée sur un pic (des dizaines de tours dans une courte fenêtre) ou en régime stable. Les pics font sauter les limites à la minute, le trafic soutenu fait sauter les quotidiennes.
• Confirmez le modèle. Certains modèles passent par un unique fournisseur avec un plafond serré (les modèles siglés Anthropic via OpenRouter partagent les limites du compte Anthropic maison).

Correctifs :

• Respectez l'en-tête Retry-After de la réponse. Sur 429 comme sur 503, OpenRouter renvoie un Retry-After en secondes. Attendez ce délai avant de retenter, puis utilisez un backoff exponentiel avec jitter si ça persiste.
• Configurez une chaîne de modèles de fallback (Cause 4 plus bas). Le tableau de modèles est le correctif le plus efficace ici parce que Hermes retente automatiquement avec le modèle suivant au lieu de rater le tour.
• Si un modèle précis tombe sans arrêt, regardez BYOK. Amener votre propre clé Anthropic ou OpenAI à OpenRouter vous donne les limites de votre propre compte upstream au lieu de partager le pool d'OpenRouter.

Cause 3 : crédits épuisés en pleine conversation (402)

Symptôme : l'agent a tenu les 30 premiers tours, puis chaque requête renvoie 402 insufficient_credits. Le tableau de bord OpenRouter affiche un solde de 0,00 $.

Ce qui se passe : OpenRouter est un solde prépayé, pas une facture mensuelle. Dès que le solde touche zéro, chaque requête est refusée avec 402 jusqu'au rechargement. Les utilisateurs de modèle gratuit voient aussi 402 quand le quota gratuit du jour est épuisé (même code que l'épuisement de crédit payant, ce qui prête à confusion mais reste cohérent avec la doc OpenRouter).

Correctifs :

• Activez l'auto-topup sur le tableau de bord OpenRouter. Fixez un seuil (par ex. ajouter 10 $ automatiquement quand le solde descend sous 2 $). C'est le correctif unique qui évite les 402 en production.
• Fixez un plafond de dépense mensuelle sur le même tableau pour éviter que l'auto-topup ne se transforme en mauvais mois silencieux.
• Si vous êtes en BYOK sur le tier Starter de Hermify, la clé OpenRouter est la vôtre et le solde est à vous de recharger. Hermify n'avance pas de crédits à votre place.

N'implémentez pas de retries côté client pour le 402. Chaque retry est un nouvel appel qui renvoie aussi 402, et OpenRouter les compte contre votre rate limit même quand ils échouent.

Cause 4 : aucune chaîne de fallback configurée

Symptôme : la moindre panne d'un modèle unique quelque part dans le réseau de fournisseurs OpenRouter met votre agent hors service jusqu'à ce que l'upstream se rétablisse. Un 429 sur le modèle principal devient une session cassée.

Ce qui se passe : par défaut, Hermes Agent envoie une requête en nommant exactement un modèle. Si ce modèle est rate-limité ou si tous ses fournisseurs sont à la capacité, OpenRouter renvoie l'erreur et Hermes n'a nulle part où router. Vous récoltez une ligne rouge et le tour est perdu.

Le correctif est le paramètre models d'OpenRouter, qui accepte un tableau de modèles par ordre de priorité. Si le premier renvoie une erreur, OpenRouter essaie le suivant, puis le suivant. C'est seulement quand le dernier échoue aussi que l'erreur remonte à Hermes.

Configurez une chaîne de 3 modèles de fallback dans ~/.hermes/config.yaml. Un exemple orienté production :

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

Cette chaîne vous donne un primaire solide (DeepSeek V4-Pro pour le raisonnement chargé en outils), un secondaire rapide et fiable d'une autre famille de fournisseurs et deux fallbacks supplémentaires sur d'autres clouds. Si DeepSeek est dégradé, la requête bascule sur Anthropic sans perdre le tour. Le billet sur le meilleur fournisseur de modèles pour Hermes Agent creuse les arbitrages entre familles de fournisseurs.

Règles de pouce pour la chaîne :

• Choisissez des modèles de familles de fournisseurs différentes. Deux modèles OpenAI tombent en même temps pendant un incident OpenAI.
• Ordonnez par qualité d'abord, coût ensuite. La chaîne descend de haut en bas et s'arrête au premier succès.
• Gardez-la entre 3 et 5 entrées. Dix fallbacks, c'est dix retries séquentiels un mauvais jour, ce qui est pire qu'un échec franc.

Cause 5 : tempêtes de retries venant de Hermes lui-même

Symptôme : un unique 429 déclenche des centaines de requêtes échouées dans le log, chacune aggravant le rate limit. Le tableau de bord montre un pic de requêtes exactement quand tout a cassé.

Ce qui se passe : sans backoff exponentiel, Hermes retente immédiatement une requête rate-limitée, ce qui déclenche le même rate limit, qui retente encore. La boucle de retry transforme une erreur récupérable en panne auto-infligée. C'est la version OpenRouter du classique stampede côté client.

Correctifs :

• Vérifiez que Hermes respecte bien Retry-After. Les versions récentes le font par défaut ; certains anciens forks non. Regardez la version avec hermes --version et mettez à jour si vous êtes en retard.
• Mettez en place une file à token bucket si vous faites tourner Hermes contre un compte mono-tenant. Imposer un écart minimal de 3 secondes entre requêtes élimine complètement les 429 sur un setup mono-utilisateur.
• Si la boucle de retry a déjà eu lieu, attendez 5 minutes avant de redémarrer l'agent. Le rate limiter d'OpenRouter a une fenêtre de chauffe, et les redémarrages immédiats étendent le blocage.

Le même schéma d'échec apparaît sur toute intégration d'API à fort volume, pas seulement OpenRouter. Voir le debugging et l'observabilité de Hermes Agent pour les conventions de logs qui rendent ça diagnosticable.

Quand arrêter de veiller sur le fournisseur

Chaque correctif de ce billet est un petit ajustement du câblage de la couche modèle. Le tableau models plus l'auto-topup OpenRouter couvrent 90 % de ce qui casse. Le reste, c'est de la patience et le bon traitement du Retry-After.

Ce qui brûle du temps, c'est de découvrir tout ça l'après-midi où votre agent s'arrête au milieu d'un projet, et de réaliser à ce moment-là que le plafond gratuit a sauté, la chaîne de fallback n'a jamais été configurée, et la boucle de retry a transformé un petit soubresaut en panne de deux heures. Si vous préférez ne pas apprendre la taxonomie d'erreurs d'OpenRouter à la dure, Hermify fait tourner un Hermes Agent géré sur Telegram avec la chaîne de fallback déjà câblée, une clé OpenRouter mesurée (apportez la vôtre ou utilisez la nôtre) et un seuil de topup qui vous maintient au-dessus de zéro. Votre clé BYOK reste à vous, mais ce n'est plus vous qui êtes de garde pour les 429.

Démarrez avec Hermify et sautez le postmortem de tempête de retries.

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