guide

OpenRouter 429 "Provider Returned Error" beheben: Rate Limits, Upstream-Anbieter und Fallback-Optionen

EvoLink Team

Product Team

13. Mai 2026

9 Min. Lesezeit

Wenn Ihre OpenRouter-Anfragen mit 429 oder "provider returned error" fehlschlagen, hängt die Lösung davon ab, wo der Fehler tatsächlich entsteht.

Diese beiden Fehler sehen in Ihren Logs aehnlich aus, haben aber unterschiedliche Ursachen:

429 Too Many Requests: Ihre Anfrage wurde abgelehnt, weil ein Rate Limit erreicht wurde
Provider returned error: OpenRouter hat Ihre Anfrage angenommen, aber der Upstream-Modellanbieter (OpenAI, Anthropic, Google usw.) hat einen Fehler zurückgegeben

Wenn Sie die beiden verwechseln, wenden Sie die falschen Korrekturen an. Dieser Leitfaden hilft Ihnen, die Ursache zu isolieren und die richtige Massnahme zu waehlen.

Zusammenfassung

Ein 429 von OpenRouter selbst bedeutet, dass Sie das Rate Limit oder Kontingent von OpenRouter erreicht haben.
Ein "provider returned error" bedeutet, dass der Upstream-Anbieter die Anfrage abgelehnt hat -- nicht OpenRouter.
Pruefen Sie Response-Header und Fehlerinhalt, um die beiden zu unterscheiden.
Die Lösung ist unterschiedlich: OpenRouter-429 erfordert Key-/Tier-Änderungen; Provider-Fehler erfordern Upstream-Diagnose oder Routenaenderungen.
Für produktive Workloads sollten Sie Fallbacks einrichten, bevor der Fehler auftritt.

Schritt 1: Die Fehlerantwort sorgfaeltig lesen

Wenn Sie einen Fehler erhalten, achten Sie auf diese drei Dinge:

Signal	Wo Sie es finden	Was es Ihnen sagt
HTTP-Statuscode	Response-Status	429 = Rate Limit; 502/503 = Upstream-Ausfall
Fehlertext	`error.message` in der JSON-Antwort	Oft steht dort "provider returned error" oder eine spezifische Rate-Limit-Meldung
Response-Header	`x-ratelimit-remaining`, `retry-after`	Ob OpenRouter selbst Sie drosselt

Ein typischer OpenRouter-429 sieht so aus:

{
  "error": {
    "code": 429,
    "message": "Rate limit exceeded. Please slow down."
  }
}

Ein typischer Provider-Fehler sieht anders aus:

{
  "error": {
    "code": 502,
    "message": "Provider returned error: [upstream error details]"
  }
}

Die Unterscheidung ist wichtig, weil unterschiedliche Korrekturen erforderlich sind.

Schritt 2: Die Fehlerquelle identifizieren

Verwenden Sie diesen Entscheidungsbaum:

Anfrage fehlgeschlagen
├── HTTP 429 + OpenRouter-Rate-Limit-Meldung
│   → Ursache: Rate Limit auf OpenRouter-Ebene
│   → Lösung: Anfragerate senken, Tier upgraden oder Verzoegerung einfuegen
│
├── HTTP 429 + "provider returned error" in der Meldung
│   → Ursache: Upstream-Provider-Rate-Limit weitergereicht
│   → Lösung: Provider-Kontingent pruefen, Modell wechseln oder Fallback-Route hinzufuegen
│
├── HTTP 502/503 + "provider returned error"
│   → Ursache: Upstream-Provider-Ausfall oder voruebergehender Fehler
│   → Lösung: Mit Backoff wiederholen, Anbieter wechseln oder Fallback nutzen
│
└── HTTP 400/401 + Fehlermeldung
    → Ursache: Ungueltige Anfrage, ungueltiger Key oder Modell nicht gefunden
    → Lösung: API-Key, Modell-ID und Anfrageformat pruefen

Schritt 3: OpenRouter-eigene 429-Fehler beheben

Wenn der 429-Fehler von OpenRouter selbst kommt (nicht vom Provider weitergeleitet), pruefen Sie der Reihe nach:

3.1 Aktuelles Rate-Limit-Tier pruefen

OpenRouter wendet Rate Limits basierend auf Ihrem Konto-Tier an. Nutzer im kostenlosen Tier haben deutlich niedrigere Limits als zahlende Nutzer.

Massnahme: Pruefen Sie Ihr OpenRouter-Dashboard auf aktuelle Limits und Nutzung.

3.2 Anfragerate reduzieren

Wenn Sie Anfragen schneller senden, als Ihr Tier erlaubt:

import asyncio
import random

async def call_with_backoff(make_request, max_retries=5):
    for attempt in range(max_retries):
        try:
            return await make_request()
        except Exception as e:
            if "429" in str(e) and attempt < max_retries - 1:
                # Respect retry-after if present, otherwise use jittered backoff
                delay = min(30, (2 ** attempt) + random.random())
                await asyncio.sleep(delay)
            else:
                raise

3.3 Traffic über die Zeit verteilen

Agent-Workloads erzeugen häufig Burst-Muster. Statt 50 Anfragen gleichzeitig zu senden:

Verwenden Sie ein Semaphor, um die Parallelitaet zu begrenzen
Fuegen Sie eine kleine Verzoegerung zwischen Batches ein
Trennen Sie Vordergrund- und Hintergrund-Warteschlangen

Schritt 4: Upstream-Provider-Fehler beheben

Wenn die Fehlermeldung "provider returned error" enthaelt, liegt das Problem beim Upstream-Anbieter. OpenRouter hat Ihre Anfrage weitergeleitet, aber der Modellanbieter hat sie abgelehnt.

4.1 Haeufige Upstream-Ursachen

Upstream-Ursache	Was Sie sehen	Wie Sie es verifizieren
Provider-Rate-Limit	Durchgereichter 429	Pruefen Sie, ob dasselbe Modell mit niedrigerer Anfragerate funktioniert
Provider-Ausfall	Durchgereichter 502/503	Pruefen Sie die Status-Seite des Anbieters (z. B. status.openai.com)
Modell veraltet oder nicht verfuegbar	404 oder Modell nicht gefunden	Pruefen Sie, ob die Modell-ID noch in der OpenRouter-Modellliste gueltig ist
Regionale Beschraenkung	403 oder Zugriff verweigert	Einige Anbieter beschraenken den Zugang nach Geografie
Eingabe zu gross	400 mit Kontext-/Token-Meldung	Pruefen Sie, ob Ihre Eingabe das Kontextfenster des Modells ueberschreitet

4.2 Zu einer anderen Provider-Route wechseln

OpenRouter leitet Anfragen an Upstream-Anbieter weiter. Wenn ein Anbieter Sie drosselt, koennte dasselbe Modell über einen anderen Anbieter-Pfad verfuegbar sein.

Pruefen Sie, ob:

Das Modell mehrere Provider-Optionen auf OpenRouter hat
Sie Provider-Praeferenzen in Ihrer Anfrage konfigurieren können
Ein Fallback-Modell mit aehnlichen Faehigkeiten verfuegbar ist

4.3 Retry-Logik hinzufuegen, die Fehlertypen unterscheidet

Wiederholen Sie nicht alle Fehler auf die gleiche Weise:

async def smart_retry(make_request, max_retries=3):
    for attempt in range(max_retries):
        try:
            return await make_request()
        except Exception as e:
            error_msg = str(e)

            # Do NOT retry: bad request, auth error, model not found
            if any(code in error_msg for code in ["400", "401", "404"]):
                raise

            # Retry with backoff: rate limit or provider error
            if any(code in error_msg for code in ["429", "502", "503"]):
                delay = min(30, (2 ** attempt) + random.uniform(0, 1))
                await asyncio.sleep(delay)
            else:
                raise

Schritt 5: Fallback im Voraus planen

In der Produktion ist die Frage nicht, ob Upstream-Fehler auftreten werden -- sondern ob Ihr System dabei kontrolliert degradiert oder abstuerzt.

Fallback-Checkliste

Fallback-Ebene	Was zu implementieren ist	Warum
Retry mit Backoff	Exponentielles Backoff mit Jitter unter Beachtung von `retry-after`	Behandelt voruebergehende Fehler, ohne die Last zu verstaerken
Modell-Fallback	Bei Ausfall des primaeren Modells auf eine leistungsfaehige Alternative umleiten	Haelt den Workflow am Laufen, wenn ein Modellpfad ausfaellt
Anbieter-Fallback	Wenn ein Anbieter Fehler liefert, eine andere Route versuchen	Reduziert die Abhaengigkeit von einem einzelnen Anbieter
Warteschlange + Circuit Breaker	Stoppen des Sendens an einen fehlgeschlagenen Pfad nach N aufeinanderfolgenden Fehlern	Verhindert Retry-Stuerme, die das Problem verschlimmern
Kontrollierte Degradierung	Kleinerer Kontext, guenstigeres Modell oder zwischengespeicherte Antwort	Besser als ein harter Ausfall für den Endnutzer

Wann ein einheitliches API-Gateway sinnvoll ist

Wenn Sie Fallback-Logik auf OpenRouter aufbauen, um Upstream-Ausfaelle zu behandeln, bauen Sie im Grunde eine Routing-Schicht auf einer Routing-Schicht auf.

An diesem Punkt kann es einfacher sein, ein Gateway zu verwenden, das Provider-Routing, Fallback und Modellauswahl als eingebaute Funktion bietet -- statt dies im Anwendungscode zu loesen.

EvoLink's Smart Router erledigt das auf Gateway-Ebene:

Automatisches Routing über verschiedene Anbieter
Gibt das tatsächlich verwendete Modell in der Antwort zurück
OpenAI-kompatibles Anfrageformat -- kein Umschreiben von Code noetig
Keine separate Routing-Gebuehr

curl https://api.evolink.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "evolink/auto",
    "messages": [
      {"role": "user", "content": "Your prompt here"}
    ]
  }'

Das ersetzt nicht die Notwendigkeit von clientseitiger Retry-Logik, verlagert aber die Anbieterauswahl und das Fallback-Management aus Ihrem Anwendungscode.

Fehlerursachen-Baum (Referenz)

OpenRouter-Anfrage fehlgeschlagen
│
├── 429 von OpenRouter
│   ├── Limit des kostenlosen Tiers → Konto upgraden
│   ├── Burst-Traffic → Parallelitaetssteuerung hinzufuegen
│   └── Dauerhaft hohes Volumen → Tier-Limits pruefen
│
├── "Provider returned error"
│   ├── Upstream 429
│   │   ├── Provider-Rate-Limit → Rate senken oder Anbieter wechseln
│   │   └── Geteiltes Kontingent erschoepft → Org-Level-Limits pruefen
│   ├── Upstream 502/503
│   │   ├── Provider-Ausfall → Status-Seite pruefen, warten oder wechseln
│   │   └── Voruebergehender Fehler → mit Backoff wiederholen
│   └── Upstream 400
│       ├── Kontext zu lang → kuerzen oder Modell wechseln
│       ├── Ungueltige Parameter → API-Dokumentation pruefen
│       └── Modell veraltet → Modell-ID überpruefen
│
└── Andere Fehler
    ├── 401 → ungueltiger API-Key
    ├── 404 → Modell nicht gefunden
    └── Netzwerkfehler → Verbindung pruefen

Naechste Schritte

Aktuellen Fehler pruefen: Verwenden Sie Schritt 2, um festzustellen, ob es sich um einen OpenRouter-429 oder einen Provider-Fehler handelt.
Gezielte Korrektur anwenden: Wenden Sie keine Rate-Limit-Korrekturen auf Provider-Fehler an und umgekehrt.
Strukturierte Retry-Logik hinzufuegen: Unterscheiden Sie im Code zwischen wiederholbaren und nicht wiederholbaren Fehlern.
Fallback vorab planen: Produktionssysteme sollten niemals von einem einzelnen Upstream-Pfad abhaengen.

FAQ

Was bedeutet "provider returned error" bei OpenRouter?

Es bedeutet, dass OpenRouter Ihre Anfrage empfangen und an den Upstream-Modellanbieter weitergeleitet hat, dieser jedoch einen Fehler zurückgegeben hat. Der Fehler stammt nicht von OpenRouter selbst, sondern von OpenAI, Anthropic, Google oder dem jeweiligen Anbieter, der das Modell bereitstellt.

Ist ein 429 von OpenRouter dasselbe wie ein 429 vom Upstream-Anbieter?

Nein. Ein OpenRouter-eigener 429 bedeutet, dass Sie die Rate Limits von OpenRouter selbst erreicht haben. Ein als "provider returned error" weitergeleiteter Provider-429 bedeutet, dass der Upstream-Anbieter die Anfrage abgelehnt hat. Die Lösungen sind unterschiedlich.

Sollte ich bei "provider returned error" einen Retry durchfuehren?

Das hängt vom Fehlertyp ab. Wenn der Upstream-Anbieter 502/503 (voruebergehender Fehler) zurückgegeben hat, ist ein Retry mit Backoff sinnvoll. Wenn er 400 (ungueltige Anfrage) oder 404 (Modell nicht gefunden) zurückgegeben hat, hilft Wiederholen nicht -- beheben Sie stattdessen die Anfrage.

Wie finde ich heraus, ob das Problem mein API-Key, mein Kontingent oder der Anbieter ist?

Pruefen Sie in dieser Reihenfolge: (1) Ist Ihr API-Key gueltig? Versuchen Sie eine einfache Testanfrage. (2) Pruefen Sie Ihr OpenRouter-Dashboard auf Kontingent- und Rate-Limit-Nutzung. (3) Wenn Key und Kontingent in Ordnung sind, liegt der Fehler wahrscheinlich beim Upstream-Anbieter -- pruefen Sie die Fehlermeldung auf Details.

Kann ein einheitliches API-Gateway Provider-Fehler eliminieren?

Kein Gateway kann verhindern, dass Upstream-Anbieter ausfallen. Aber ein Gateway mit integriertem Routing und Fallback kann automatisch zu einem alternativen Anbieter oder Modell wechseln, wenn ein Pfad ausfaellt, und so die Auswirkungen auf Ihre Anwendung reduzieren.

Wann sollte ich von OpenRouter zu einer anderen Routing-Lösung wechseln?

Ziehen Sie einen Wechsel in Betracht, wenn: (1) Provider-Fehler ein wiederkehrendes Produktionsproblem sind, (2) Sie Fallback-Logik benoetigen, die OpenRouter nicht bietet, (3) Ihr Workload mehrere Modalitaeten umfasst (Text + Bild + Video) oder (4) Sie Routing-Entscheidungen auf Gateway-Ebene statt im Anwendungscode verwalten moechten.

Alle Beiträge

#openrouter 429 #provider returned error #rate limit #fehlerbehebung #KI-API-Fehler