Claude API 429 rate_limit_error — Ursachen und eine dauerhafte Lösung

Ein 429 von der Claude-API bedeutet, dass Sie eines der Anthropic-Limits pro Minute überschritten haben — Anfragen, Eingabe-Token oder Ausgabe-Token. Die Lösung lautet selten „länger warten“: Beachten Sie retry-after, fügen Sie Backoff mit Jitter hinzu und glätten Sie Spitzen. Hier ist der vollständige Leitfaden.

Der Fehler

response (HTTP 429)

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "Number of request tokens has exceeded your per-minute rate limit"
  }
}

Ursachen und Lösungen im Überblick

Ursache	Lösung
Limit für Anfragen pro Minute (RPM) erreicht	Stellen Sie Anfragen clientseitig in eine Warteschlange und beachten Sie vor dem Retry den retry-after-Header.
Limit für Eingabe-Token pro Minute (ITPM) erreicht — große Prompts, wenige Anfragen	Kürzen Sie den abgerufenen Kontext und aktivieren Sie Prompt-Caching, damit zwischengespeicherte Token bei unterstützten Tarifen nicht mehr gegen Sie zählen.
Limit für Ausgabe-Token pro Minute (OTPM) erreicht	Setzen Sie max_tokens realistisch — bei langen Generierungen ist OTPM häufig die erste Obergrenze.
Spitzenverkehr (Cron startet alles um :00)	Fügen Sie den Zeitplänen Jitter hinzu und verteilen Sie Batch-Jobs über die Minute.

Lesen Sie die Antwort vor dem Retry

Anthropic gibt einen retry-after-Header mit der Wartezeit in Sekunden zurück, und die Fehlermeldung nennt das überschrittene Limit. Wer ohne sie zu lesen sofort wiederholt, macht aus einem einzelnen 429 einen 429-Sturm.

Exponentielles Backoff mit Jitter hinzufügen

Wiederholen Sie nur wiederholbare Status (429, 500, 529), niemals Authentifizierungs- oder Validierungsfehler. Dieses Snippet funktioniert unverändert direkt mit Anthropic und mit jedem OpenAI-kompatiblen Endpunkt:

backoff.py

import time, random
from openai import OpenAI, APIStatusError

client = OpenAI(base_url="https://api.kunavo.com/v1", api_key="sk-kn-...")

def with_backoff(fn, max_retries=5):
    for attempt in range(max_retries):
        try:
            return fn()
        except APIStatusError as e:
            if e.status_code not in (429, 500, 529):
                raise                      # don't retry auth/validation errors
            retry_after = e.response.headers.get("retry-after")
            delay = float(retry_after) if retry_after else min(2 ** attempt, 30)
            time.sleep(delay + random.uniform(0, 0.5))   # jitter avoids herds
    raise RuntimeError("retries exhausted")

resp = with_backoff(lambda: client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "ping"}],
    max_tokens=32,
))
print(resp.choices[0].message.content)

Reduzieren Sie die Token, nicht nur die Anfragen

Wenn die Meldung auf Tokenlimits hinweist, reicht Backoff allein nicht. Kürzen Sie abgerufene Abschnitte, begrenzen Sie max_tokens und aktivieren Sie Prompt-Caching — ein großer, stabiler System-Prompt, der zu 10 % des Eingabetokenpreises abgerechnet wird, verringert auch den Druck auf das ITPM-Limit.

Wenn Sie Kunavo verwenden

Claude über Kunavo aufzurufen entfernt Ratenlimits nicht auf magische Weise, verändert aber die Kosten eines Fehlers: Fehlgeschlagene Anfragen, einschließlich 429, werden niemals berechnet, und das Nutzungs-Dashboard pro Schlüssel zeigt genau, welcher Schlüssel und welches Modell Spitzen erzeugt, damit Sie sie glätten können. Das Backoff-Snippet oben funktioniert unverändert — nur base_url ist anders. Ratenlimits sind eine Durchsatzgrenze, kein Preis — die tatsächlichen Kosten eines Claude-Aufrufs pro 1 Mio. Token sowie die offizielle Anthropic-Preisliste neben unserer finden Sie unter Preisliste der Anthropic-Claude-API.

Häufig gestellte Fragen

Beseitigt ein Upgrade meiner Anthropic-Nutzungsstufe 429-Fehler?

Höhere Nutzungsstufen erhöhen die Limits pro Minute, sodass 429-Fehler seltener werden. Jedes feste Limit kann jedoch durch eine Lastspitze erreicht werden. Produktionscode benötigt unabhängig von der Nutzungsstufe Backoff.

Soll ich einen 429 sofort wiederholen?

Nein — beachten Sie den retry-after-Header (oder verwenden Sie exponentielles Backoff mit Jitter, falls er fehlt). Sofortige Wiederholungen verlängern das ratenbegrenzte Zeitfenster und können zu einer längeren Sperre führen.

Kosten fehlgeschlagene 429-Anfragen Geld?

Anthropic berechnet abgelehnte Anfragen nicht, und Kunavo ebenfalls nicht — fehlgeschlagene Anfragen werden nie in Rechnung gestellt. Die Kosten eines 429-Fehlers sind Latenz, keine Dollarbeträge.