429-Fehler rate_limit_error in der Claude API — Bedeutung und Lösung

429 bedeutet „langsamer“, nicht „Ihr Geld ist aufgebraucht“. Der Unterschied ist wichtig: Die Lösung für das eine ist Warten, für das andere Aufladen — wer beides verwechselt, verbringt Stunden mit der Fehlersuche am falschen Ort.

Der Fehler

resposta (HTTP 429)

{
  "type": "error",
  "error": { "type": "rate_limit_error",
             "message": "Number of requests has exceeded your rate limit" }
}

Ursachen und Lösungen im Überblick

Ursache	Lösung
Anfragen pro Minute über dem Limit Ihres Kontos	Stellen Sie Anfragen im Client in eine Warteschlange und begrenzen Sie die Parallelität, statt alles auf einmal zu senden.
Tokens pro Minute über dem Limit	Lange Prompts verbrauchen das Tokenkontingent deutlich früher als das Anfragekontingent. Reduzieren Sie den Kontext oder teilen Sie die Arbeit auf.
Mehrere Prozesse verwenden denselben Schlüssel	Das Limit gilt für den Schlüssel, nicht für den Prozess. Parallele Worker werden auf dasselbe Kontingent angerechnet.
Retry ohne Backoff	Sofortiges Wiederholen hält Sie dauerhaft über dem Limit. Exponentielles Backoff mit Jitter ist erforderlich.

Beachten Sie retry-after, wenn es vorhanden ist

Wenn die Antwort den Header retry-after enthält, ist er keine Empfehlung, sondern die genaue Zeitspanne, nach der die Anfrage wieder akzeptiert wird. Kürzeres Warten garantiert einen weiteren 429-Fehler.

retry_after.py

import time
from openai import APIStatusError

try:
    resp = client.chat.completions.create(model=MODELO, messages=msgs)
except APIStatusError as e:
    if e.status_code == 429:
        espera = float(e.response.headers.get("retry-after", 5))
        time.sleep(espera)
        resp = client.chat.completions.create(model=MODELO, messages=msgs)
    else:
        raise

Begrenzen Sie die Parallelität an der Quelle

Die häufigste Ursache ist nicht das Gesamtvolumen, sondern eine Spitze: Zwanzig gleichzeitig gesendete Anfragen überschreiten ein Limit, das sechzig über eine Minute verteilte Anfragen nicht überschreiten. Ein Semaphor löst, was ein Retry allein nicht löst.

concorrencia.py

import asyncio

LIMITE = asyncio.Semaphore(4)   # no máximo 4 chamadas simultâneas

async def chamar(msgs):
    async with LIMITE:
        return await client.chat.completions.create(
            model=MODELO, messages=msgs)

Bestätigen Sie, dass es ein Limit und kein Guthaben ist

Ein 429 bedeutet niemals fehlendes Guthaben — dafür steht 402. Wenn Ihr Log beide Fälle vermischt, trennen Sie sie vor der Untersuchung nach Status: Die Lösung für 429 ist Timing, die für 402 ist Aufladen. Das Wiederholen eines 402 schlägt dauerhaft fehl.

Wenn Sie Kunavo verwenden

Bei Kunavo gelten die Limits pro Schlüssel, während das Guthaben in einer separaten Prepaid-Wallet geführt wird. Daher erscheinen beide Fälle mit unterschiedlichen Statuscodes: 429 für ein Ratenlimit und 402, wenn das Guthaben den Aufruf nicht abdeckt — niemals einer als der andere getarnt. Abgewiesene Anfragen werden nicht berechnet. Die Tokenpreise, die bestimmen, wie viel Guthaben jeder Aufruf verbraucht, finden Sie in unserem Preisleitfaden für die Claude API.

Häufig gestellte Fragen

Bedeutet 429, dass mein Guthaben aufgebraucht ist?

Nein. Fehlendes Guthaben ist 402. Bei 429 geht es um die Geschwindigkeit: Sie haben in kurzer Zeit zu viele Anfragen oder Tokens gesendet; Warten behebt das Problem.

Wie lange sollte ich warten?

Wenn der Header retry-after vorhanden ist, genau diese Zeit. Ohne ihn verwenden Sie exponentielles Backoff ab 1–2 Sekunden mit Jitter bis zu einer Obergrenze von 30–60 Sekunden.

Hilft eine Erhöhung des Limits?

Wenn das Volumen tatsächlich hoch ist, kann das helfen; die meisten 429-Fehler entstehen jedoch durch kurze Spitzen. Eine Begrenzung der Parallelität löst das Problem oft ohne jede Änderung des Limits.