OpenRouter 429 beheben: Provider-Fehler oder Rate Limit?

Ein 429-Fehler von OpenRouter heißt nicht automatisch, dass Ihr OpenRouter-Konto ein Limit erreicht hat. Möglicherweise drosselt auch der ausgewählte Upstream-Provider Ihre Anfragen. Sichern Sie deshalb zunächst eine vollständige fehlgeschlagene Antwort: HTTP-Status, Response-Header und JSON-Body zeigen, an welchem Limit Sie ansetzen müssen.

Bevor Sie etwas ändern: eine 429-Antwort richtig einordnen

Klären Sie erst die Ursache, bevor Sie Guthaben kaufen, einen Key austauschen oder Retries einbauen. Die typisierten Felder und Response-Header von OpenRouter sind belastbarer als die lesbare Fehlermeldung, denn diese kann Text enthalten, den ein Upstream-Provider weitergereicht hat.

Die Referenz zu Fehlern und Debugging von OpenRouter definiert den Umschlag mit error.code, error.message und optionalen error.metadata, einschließlich error_type = "rate_limit_exceeded". Erfolgreiche Antworten enthalten laut Dokumentation normalerweise keine X-RateLimit-*-Header. Eine Überlastung beim Provider wird separat als provider_overloaded typisiert und entspricht normalerweise einem 503-Fehler.

429-Limit direkt bei OpenRouter beheben

Ein 429 auf OpenRouter-Ebene wird durch das Plattformkontingent bestimmt, das dem Konto und der Modellklasse zugeordnet ist. Laut der am 31. Juli 2026 geprüften offiziellen Dokumentation zu Rate Limits gelten für kostenlose Modellvarianten mit der Endung :free sowohl Limits pro Minute als auch pro Tag.

Die Limit-Richtlinie stellt klar, dass zusätzliche Konten oder Keys die global verwaltete Kapazität nicht erhöhen. Einen gültigen Key zu ersetzen setzt ein Plattformlimit daher nicht zurück.

Über den GET /api/v1/key-Endpunkt können Sie Nutzung und Kreditlimits prüfen:

curl https://openrouter.ai/api/v1/key \
  -H "Authorization: Bearer $OPENROUTER_API_KEY"

Bei einem Plattform-429 verwenden Sie den Reset-Header aus der Fehlerantwort und gehen in dieser Reihenfolge vor:

1. Sofortige Retries stoppen und bis X-RateLimit-Reset warten.
2. Die Zahl paralleler Anfragen reduzieren, nicht nur die Anfragen pro Sekunde. Ein Schub paralleler Worker kann das Limit überschreiten, bevor auch nur ein Worker den ersten 429 sieht.
3. Aufgaben hinter einem gemeinsamen Limiter einreihen, damit nicht alle Worker gleichzeitig aufwachen und erneut versuchen.
4. Wenn die Last nicht in das Kontingent für Gratis-Modelle passt, diesen Traffic auf eine passende kostenpflichtige Modellvariante verlagern.

Ein negatives Guthaben oder ein ausgeschöpftes Kreditlimit pro Key sollte einen 402 auslösen. Ein Upstream-Provider kann dagegen auch bei einem finanzierten Konto einen 429 zurückgeben. Der OpenRouter-Preisleitfaden behandelt die davon getrennten Fragen zu Kosten und Guthaben.

429 mit „Provider Returned Error“ beheben

Ein vom Provider zurückgegebener 429 bedeutet, dass OpenRouter einen Upstream-Inferenzprovider erreicht hat, der die Anfrage in diesem Moment nicht akzeptiert. Achten Sie auf den typisierten Rate-Limit-Wert und die Provider-Metadaten: Zusätzliches OpenRouter-Guthaben schafft bei diesem Provider keine Kapazität.

Die offizielle Limit-Referenz weist darauf hin, dass das Routing möglicherweise bereits alternative Provider versucht hat, bevor der Fehler zurückgegeben wird. Retry-After wird ergänzt, wenn jeder versuchte Provider einen Retry-Hinweis geliefert hat. Praktisch helfen diese Maßnahmen:

1. Retry-After beachten, statt dieselbe Anfrage sofort erneut zu generieren.
2. Zu strikte Provider-Beschränkungen entfernen, wenn dadurch nur eine überlastete Route übrig bleibt.
3. Prüfen, ob Provider-Fallbacks für die Anfrage erlaubt sind.
4. Einen Modell-Fallback konfigurieren, wenn der Abschluss der Aufgabe wichtiger ist als genau dieses Modell.

Ein Zed-Nutzer mit Guthaben stieß bei moonshotai/kimi-k2:free auf ein Upstream-Limit; ein neu generierter Key half nicht. Ein Zed-Mitwirkender erklärte:

„Das ist kein Zed-Fehler. OpenRouter teilt Ihnen mit, dass der verwendete Upstream-Provider Sie per Rate Limit drosselt.“ Quelle: zed-industries/zed issue #35153

Beachten Sie ein kurzes Retry-After. Einen Fallback auf ein Gratis-Modell sollten Sie nur nutzen, wenn der Abschluss der Aufgabe wichtiger ist als das exakt gewählte Modell.

Wenn der Fehler in Janitor AI, Zed oder SillyTavern erscheint

Bewahren Sie den Rohfehler auf, vermeiden Sie wiederholtes Neugenerieren und ändern Sie bei providerseitigen Fehlern das Modell oder die zugelassene Route. Einen Key erneut einzugeben ist nur sinnvoll, um die Speicherung im Client zu korrigieren; Kapazität wird dadurch nicht zurückgesetzt.

Retries ohne Endlosschleife bei 429

Wiederholen Sie nur Rate-Limit-Fehler, begrenzen Sie die Zahl der Versuche und bevorzugen Sie die vom Server vorgegebene Wartezeit. Fehlt ein Retry-Hinweis, verwenden Sie exponentiellen Backoff mit Obergrenze und Jitter, damit parallele Clients nicht gleichzeitig den nächsten Burst auslösen.

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

function retryDelayMs(response, attempt) {
  const retryAfter = response.headers.get("retry-after");
  if (retryAfter) {
    const seconds = Number(retryAfter);
    if (Number.isFinite(seconds)) return Math.max(0, seconds * 1000);

    const dateMs = Date.parse(retryAfter);
    if (Number.isFinite(dateMs)) return Math.max(0, dateMs - Date.now());
  }

  const capMs = 30_000;
  const exponentialMs = Math.min(capMs, 1000 * 2 ** attempt);
  return Math.random() * exponentialMs; // Full jitter
}

async function createChatCompletion(body, maxAttempts = 4) {
  for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
    const response = await fetch(
      "https://openrouter.ai/api/v1/chat/completions",
      {
        method: "POST",
        headers: {
          Authorization: `Bearer ${process.env.OPENROUTER_API_KEY}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify(body),
      },
    );

    const raw = await response.text();
    let payload;
    try {
      payload = raw ? JSON.parse(raw) : null;
    } catch {
      payload = null;
    }
    if (response.ok) return payload;

    const isRateLimit =
      response.status === 429 ||
      payload?.error?.metadata?.error_type === "rate_limit_exceeded";

    if (!isRateLimit || attempt === maxAttempts - 1) {
      const error = new Error(payload?.error?.message || raw || `HTTP ${response.status}`);
      error.status = response.status;
      error.details = payload?.error;
      throw error;
    }

    await sleep(retryDelayMs(response, attempt));
  }
}

Diese Funktion verarbeitet nicht streamende Antworten. Die gemeinsame Queue- oder Token-Bucket-Steuerung für Parallelität sollte außerhalb liegen, damit viele wartende Worker nicht gemeinsam wieder starten.

Sobald Server-Sent Events mit HTTP 200 begonnen haben, kann der Status nicht mehr zu 429 wechseln. Laut der OpenRouter-Fehlerreferenz erscheint ein späterer Fehler im Stream mit einem Fehlerobjekt und finish_reason: "error". Markieren Sie die Completion dann als fehlgeschlagen und wiederholen Sie sie nur, wenn der eingebettete Typ rate_limit_exceeded lautet. Bereits gesammelten Text sollten Sie nicht als Erfolg zurückgeben, sofern die Anwendung Teilergebnisse nicht ausdrücklich unterstützt.

FAQ

Was bedeutet „429 provider returned error“ bei OpenRouter?

Ein Upstream-Inferenzprovider hat die Anfrage wegen seines eigenen Rate- oder Kapazitätslimits abgelehnt. Bestätigen lässt sich das über error.metadata.error_type und die Provider-Metadaten.

Warum erhalte ich bei OpenRouter 429, obwohl noch Guthaben vorhanden ist?

Auch ein finanziertes Konto kann einen providerseitigen 429 erhalten. Unzureichendes Guthaben oder ein Kreditlimit pro Key führt normalerweise stattdessen zu 402.

Setzt ein neuer OpenRouter API Key das Rate Limit zurück?

Nein. Zusätzliche Keys erhöhen keine global verwalteten Limits. Ersetzen Sie einen Key nur, um Authentifizierung oder die Speicherung im Client zu korrigieren.

Wie lange sollte ich vor einem OpenRouter-Retry warten?

Verwenden Sie Retry-After, wenn der Header vorhanden ist. Bei einem Plattformlimit gilt X-RateLimit-Reset; ohne einen der beiden Hinweise nutzen Sie exponentiellen Backoff mit Obergrenze, Jitter und einer kleinen maximalen Zahl von Versuchen.

Kann OpenRouter HTTP 200 zurückgeben und dennoch mit 429 fehlschlagen?

Ja, wenn das Streaming bereits begonnen hat. Der HTTP-Status bleibt dann 200, während der SSE-Stream einen Fehler meldet und mit finish_reason: "error" endet. Prüfen Sie den eingebetteten Fehlertyp, um festzustellen, ob ein Rate Limit die Ursache war.