OpenRouter-Rate-Limit-Fehler bei Hermes Agent beheben

Ihr Agent ist mitten im Gespräch stehengeblieben

Sie sind in der dritten Runde einer endlich brauchbaren Unterhaltung mit Hermes Agent, als die Antwort leer zurückkommt und das Log eine rote Zeile zeigt: 429 Too Many Requests. Oder schlimmer, ein 402 Payment Required, weil das Modell die Anfrage komplett abgelehnt hat. Der Agent, der vor einer Stunde noch reibungslos lief, ist jetzt eine Wand aus Retry-Fehlern, und Sie sind eine Debug-Sitzung davon entfernt, den Anbieter zu wechseln.

Die Fehlercodes von OpenRouter sind präzise, sobald man weiß, was jeder bedeutet. 429 ist ein Rate-Limit und kommt aus drei verschiedenen Quellen. 402 ist eine Guthaben-Erschöpfung und verhält sich in keinem Punkt wie ein 429. 503 ist eine Nichtverfügbarkeit des Upstream-Anbieters und der einzige, um den herum sich schmerzfrei automatisieren lässt. Jeder hat eine spezifische Lösung, und der models-Array von Hermes Agent macht die meisten davon zu Nicht-Ereignissen.

OpenRouter-Fehlercodes auf einen Blick lesen

Bevor Sie an der Config schrauben, verstehen Sie, was die API Ihnen tatsächlich sagt. OpenRouter dokumentiert diese Codes explizit, und die Zahlen zählen.

Ein 429 und ein 402 sehen im Terminal ähnlich aus, verlangen aber gegensätzliche Reaktionen. Ein 402 in einer Schleife zu wiederholen verbrennt nur Ihr Retry-Budget, während der Kontostand bei null bleibt. Ein 429 mit Verstand zu wiederholen ist das ganze Spiel.

Der zweite Punkt, der die Lektüre lohnt, ist error.metadata.provider_code. Wenn ein 429 vom Upstream-Anbieter kommt, der Ihre Anfrage bedient (Anthropic, DeepSeek, OpenAI, Groq), leitet OpenRouter den ursprünglichen Fehlercode dieses Anbieters in diesem Feld weiter. Das unterscheidet ein OpenRouter-Plattformlimit von einem Upstream-Tenant-Limit, und beide erfordern unterschiedliche Lösungen.

Ursache 1: Tageskappe des kostenlosen OpenRouter-Tiers

Symptom: Gestern hat alles funktioniert, heute Morgen auch, und jetzt liefert jede Anfrage einen 429, obwohl Sie kaum Traffic senden. Tritt üblicherweise nach etwa 20 Minuten einer normalen Hermes-Sitzung auf.

Was passiert: Der kostenlose OpenRouter-Tier erlaubt 20 Anfragen pro Minute gegen Free-Modelle, gedeckelt bei 50 Anfragen pro Tag. Ein einmaliger Kauf von 10 $ Credits hebt die tägliche Untergrenze dauerhaft von 50 auf 1.000 an. Die werkzeuglastige Schleife von Hermes Agent (ein Zug ist ein API-Aufruf plus Retries) erschöpft einen 50-Anfragen-Tag innerhalb eines einzigen mittelgroßen Gesprächs.

Zuerst prüfen: Stellen Sie sicher, dass das Modell in Ihrer Config zum Free-Tier gehört. Free-Modelle bei OpenRouter tragen den Suffix :free im Slug (deepseek/deepseek-v4-flash:free). Endet Ihre model:-Zeile mit :free, gilt diese Kappe.

Sofortlösung: Fügen Sie im OpenRouter-Dashboard 10 $ Guthaben hinzu. Die Tageskappe springt für immer auf 1.000/Tag, das reicht für einen normalen Hermes-Nutzer.

Strukturelle Lösung: Leiten Sie keinen Produktions-Traffic mehr über ein Free-Modell. Free-Modelle sind für die Evaluierung, nicht für einen laufenden Agenten. Wechseln Sie zum gleichen Modell ohne :free und zahlen Sie den Tarif (DeepSeek V4-Flash ohne Suffix kostet 0,14 $/M Input, ein Tag Hermes-Nutzung sind also einstellige Cent-Beträge). Die vollständige Preis-Mathematik steht in dem günstigsten OpenRouter-Modell für Hermes Agent.

Ursache 2: Rate-Limit des Upstream-Anbieters (429 mit provider_code)

Symptom: Sie nutzen ein bezahltes Modell, das Guthaben ist gesund, und trotzdem bekommen Sie 429, wenn Hermes beschäftigt ist. Der Response-Body enthält error.metadata.provider_code mit einem Wert wie rate_limit_exceeded oder insufficient_quota.

Was passiert: OpenRouter selbst deckelt bezahlte Modelle nicht hart, aber der Upstream-Anbieter tut es. Anthropic, OpenAI und DeepSeek wenden Konto-basierte Limits gemäß Ihrem Tenancy-Tier an. Wenn OpenRouter Ihre Anfrage an den Upstream weiterleitet, lehnt der Upstream sie ab, und OpenRouter reicht diese Ablehnung als 429 durch.

Diagnose:

• Lesen Sie error.metadata.provider_code. Steht dort rate_limit_exceeded, ist es dieser Fall.
• Prüfen Sie, ob die Anfrage in einem Burst gelandet ist (Dutzende Runden in einem kurzen Fenster) oder im gleichmäßigen Betrieb. Bursts lösen Pro-Minute-Limits aus, gleichmäßiger Verkehr Pro-Tag-Limits.
• Verifizieren Sie das Modell. Manche Modelle laufen über einen einzigen Anbieter mit engem Deckel (Modelle mit Anthropic-Marke via OpenRouter teilen die Limits von Anthropics eigenem Konto).

Lösungen:

• Beachten Sie den Retry-After-Response-Header. Sowohl bei 429 als auch bei 503 liefert OpenRouter einen Retry-After-Wert in Sekunden. Warten Sie diese Zeit ab, bevor Sie erneut senden, und verwenden Sie danach exponentielles Backoff mit Jitter, falls es weiter fehlschlägt.
• Konfigurieren Sie eine Fallback-Modellkette (Ursache 4 weiter unten). Der Modell-Array ist hier die wirkungsvollste Lösung, weil Hermes automatisch mit dem nächsten Modell wiederholt, statt den Zug zu verlieren.
• Wenn ein bestimmtes Modell dauernd stolpert, prüfen Sie BYOK. Wenn Sie Ihren eigenen Anthropic- oder OpenAI-Schlüssel zu OpenRouter mitbringen, erhalten Sie die Limits Ihres eigenen Upstream-Kontos, statt sich den OpenRouter-Pool zu teilen.

Ursache 3: Guthaben mitten im Chat aufgebraucht (402)

Symptom: Der Agent hielt die ersten 30 Runden durch, dann liefert jede Anfrage 402 insufficient_credits. Das OpenRouter-Dashboard zeigt einen Kontostand von 0,00 $.

Was passiert: OpenRouter ist ein Prepaid-Guthaben, keine Monatsrechnung. Sobald der Kontostand null erreicht, wird jede Anfrage mit 402 abgelehnt, bis Sie aufladen. Nutzer von Free-Modellen sehen ebenfalls 402, wenn das Tages-Freikontingent aufgebraucht ist (verwendet denselben Code wie das Ende bezahlten Guthabens, was verwirrend, aber konsistent mit der OpenRouter-Doku ist).

Lösungen:

• Aktivieren Sie das Auto-Topup im OpenRouter-Dashboard. Legen Sie einen Schwellwert fest (z. B. automatisch 10 $ hinzufügen, wenn der Saldo unter 2 $ fällt). Das ist die einzige Lösung, die 402er in Produktion verhindert.
• Setzen Sie im gleichen Dashboard einen monatlichen Ausgabendeckel, damit das Auto-Topup nicht stillschweigend zu einem schlechten Monat wird.
• Wenn Sie BYOK auf Hermifys Starter-Tier nutzen, gehört Ihnen der OpenRouter-Schlüssel, und das Aufladen liegt bei Ihnen. Hermify streckt keine Credits für Sie vor.

Implementieren Sie keine Client-Retries für 402. Jeder Retry ist ein weiterer API-Aufruf, der ebenfalls 402 liefert, und OpenRouter rechnet sie gegen Ihr Rate-Limit an, auch wenn sie fehlschlagen.

Ursache 4: Keine Fallback-Kette konfiguriert

Symptom: Der Ausfall eines einzigen Modells irgendwo im OpenRouter-Anbieternetz nimmt Ihren Agenten komplett offline, bis der Upstream sich erholt. Ein 429 auf dem Primär-Modell wird zur zerrissenen Sitzung.

Was passiert: Standardmäßig schickt Hermes Agent eine Anfrage, die genau ein Modell benennt. Ist dieses Modell rate-limitiert oder alle seine Anbieter an der Kapazitätsgrenze, gibt OpenRouter den Fehler zurück, und Hermes hat keine Alternative. Sie bekommen eine rote Log-Zeile, und der Zug ist verloren.

Die Lösung ist der models-Parameter von OpenRouter, der einen Array von Modellen in Prioritätsreihenfolge akzeptiert. Wenn das erste Modell einen Fehler liefert, versucht OpenRouter das nächste, dann das nächste. Erst wenn auch das letzte fehlschlägt, gelangt der Fehler zurück zu Hermes.

Konfigurieren Sie eine dreistufige Fallback-Kette in ~/.hermes/config.yaml. Ein produktionsähnliches Beispiel:

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

Diese Kette gibt Ihnen einen starken Primär (DeepSeek V4-Pro für werkzeuglastiges Reasoning), einen schnellen und verlässlichen Sekundär aus einer anderen Anbieterfamilie und zwei weitere Fallbacks in verschiedenen Clouds. Ist DeepSeek gestört, wird die Anfrage ohne Zugverlust an Anthropic geroutet. Der Beitrag zum besten Modellanbieter für Hermes Agent geht tiefer in die Abwägungen zwischen Anbieterfamilien.

Faustregeln für die Kette:

• Wählen Sie Modelle aus unterschiedlichen Anbieterfamilien. Zwei OpenAI-Modelle fallen bei einem OpenAI-Vorfall gemeinsam aus.
• Ordnen Sie nach Qualität zuerst, Kosten danach. Die Kette läuft top-down und stoppt beim ersten Erfolg.
• Halten Sie sie bei drei bis fünf Einträgen. Zehn Fallbacks bedeuten an einem schlechten Tag zehn sequenzielle Retries, was schlimmer ist als ein lautes Scheitern.

Ursache 5: Retry-Stürme von Hermes selbst

Symptom: Ein einzelner 429 kaskadiert im Log zu Hunderten fehlgeschlagener Anfragen, jede verschlimmert das Rate-Limit. Das Dashboard zeigt einen Anfragen-Peak genau in dem Moment, in dem alles kaputtging.

Was passiert: Ohne exponentielles Backoff wiederholt Hermes eine rate-limitierte Anfrage sofort, was dasselbe Rate-Limit wieder auslöst, was erneut wiederholt. Die Retry-Schleife verwandelt einen behebbaren Fehler in einen selbstverschuldeten Ausfall. Es ist die OpenRouter-Version des klassischen Client-seitigen Rate-Limit-Stampedes.

Lösungen:

• Prüfen Sie, ob Hermes Retry-After respektiert. Aktuelle Versionen tun das per Default; ältere Forks möglicherweise nicht. Prüfen Sie die Version mit hermes --version und aktualisieren Sie, falls Sie hinterherhinken.
• Konfigurieren Sie eine Token-Bucket-Queue, wenn Sie Hermes gegen ein Single-Tenant-Konto fahren. Ein Mindestabstand von drei Sekunden zwischen Anfragen eliminiert 429er in einem Single-User-Setup vollständig.
• Ist die Retry-Schleife bereits passiert, warten Sie fünf Minuten, bevor Sie den Agenten neu starten. Der OpenRouter-Rate-Limiter hat ein Warm-up-Fenster, und sofortige Neustarts verlängern die Sperre.

Dasselbe Fehlermuster taucht bei jeder High-Volume-API-Integration auf, nicht nur bei OpenRouter. Für die Log-Konventionen, die das diagnostizierbar machen, siehe Hermes-Agent-Debugging und Observability.

Wann Sie aufhören sollten, den Anbieter zu babysitten

Jede Lösung in diesem Beitrag ist eine kleine Korrektur an der Verdrahtung der Modell-Schicht. Der models-Array plus Auto-Topup bei OpenRouter decken 90 % dessen ab, was kaputtgeht. Der Rest ist Geduld und die richtige Retry-After-Behandlung.

Was Zeit verbrennt, ist all das an dem Nachmittag zu entdecken, an dem Ihr Agent mitten in einem Projekt aussteigt, und dann zu merken, dass die Free-Tier-Kappe zugeschlagen hat, die Fallback-Kette nie konfiguriert war und die Retry-Schleife einen kleinen Schluckauf in einen zweistündigen Ausfall verwandelt hat. Wenn Sie die OpenRouter-Fehler-Taxonomie lieber nicht auf die harte Tour lernen möchten, betreibt Hermify einen verwalteten Hermes Agent auf Telegram mit vorverdrahteter Fallback-Kette, einem dosierten OpenRouter-Schlüssel (Sie bringen Ihren mit oder nutzen unseren) und einem Topup-Boden, der Sie über null hält. Ihr BYOK-Schlüssel bleibt Ihrer, aber Sie sind nicht mehr der Bereitschaftsdienst für 429.

Starten Sie mit Hermify und sparen Sie sich das Postmortem des Retry-Sturms.

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