API-Rate-Limiting – Headers, Exponentielle Zurücksetzung und das Überleben des 429

Sie haben eine 429 erhalten. Vielleicht ist Ihr Webhook-Handler abgestürzt. Vielleicht wurde ein Batchjob stumm abgebrochen. Die API gab Ihnen „Too Many Requests“ und eine Wand aus Antwortheaders, die Sie wahrscheinlich bereits vorbeigescrollt haben.

Diese Headers enthalten die ganze Geschichte. Hier erfahren Sie, wie Sie sie lesen und wie Sie eine Wiederholungslogik schreiben, die das Problem nicht verschlimmert.

Die Headers, die tatsächlich wichtig sind

Die meisten rate-limited APIs geben auf jede Antwort eine Variante dieser Headers zurück – nicht nur bei 429-Fehlern:

• X-RateLimit-Limit — Ihre Gesamtanzahl erlaubter Anfragen im aktuellen Fenster. GitHubs REST-API gibt authentifizierten Benutzern 5.000 pro Stunde; unauthentifizierte Anfragen erhalten 60.
• X-RateLimit-Remaining — Die Anzahl der noch übrigen Anfragen im aktuellen Fenster. Wenn dieser Wert 0 erreicht, wird die nächste Anfrage mit einer 429 zurückgegeben.
• X-RateLimit-Reset — Der Zeitpunkt, wann das Fenster zurückgesetzt wird, als Unix-Epoch-Zeitstempel. Dies ist der Header, den die meisten Entwickler ignorieren, und der nützlichste.
• X-RateLimit-Used (GitHub-spezifisch) — Anzahl der bisher verbrauchten Anfragen. Mirrors Limit - Remaining aber nützlich für Kontrollüberprüfungen.
• Retry-After — Erscheint nur bei 429-Antworten. Entweder eine Anzahl Sekunden, oder ein HTTP-Datum. Wenn die API dies sendet, verwenden Sie es – es ist präziser als jede Berechnung, die Sie selbst durchführen.

Echte GitHub-Response-Headers sehen so aus:

X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4823
X-RateLimit-Reset: 1716998400
X-RateLimit-Used: 177
X-RateLimit-Resource: core

Der X-RateLimit-Resource header ist GitHub-spezifisch: Sie verwalten getrennte Quotapools für die Core-REST-API, die Suche und GraphQL. Das Verbrauchen Ihrer Suchquota (begrenzt auf 30 Anfragen pro Minute) beeinflusst nicht Ihre Core-Quota – und umgekehrt.

Stripe ist anders

Stripe verwendet X-RateLimit-* Namen. Ihre Headers sind anders präfixiert:

Stripe-Ratelimit-Limit: 100
Stripe-Ratelimit-Remaining: 97
Stripe-Ratelimit-Reset: 1716998460

Und bei einer 429-Antwort:

Retry-After: 30

Stripes Standardbegrenzung beträgt 100 Live-Modus-Anfragen pro Sekunde, nicht pro Stunde. Das ist wichtiger, als es klingt: Ein Loop, der 500 Kunden importiert, kann diese Fenster in weniger als 5 Sekunden ausleeren, wenn Sie nicht auf Ihrer Seite auf die Begrenzung achten.

Stripe unterscheidet auch zwischen Anfragenbegrenzungen und resourcenbezogenen Begrenzungen (z. B. die Erstellung zu vieler Kunden in kurzer Zeit). Die 429-Antworttext legt fest, welche Begrenzung Sie erreicht haben – loggen Sie immer den vollständigen Text, nicht nur den Statuscode.

Die Dekodierung des Reset-Timestamps

Der X-RateLimit-Reset Wert ist ein Unix-Epoch-Timestamp. 1716998400 Zeigt Ihnen zunächst nichts, aber es ist trivial zu dekodieren: Verwenden Sie die Unix-Zeitstempel-Konverter um es in einen lesbaren UTC-Datumszeitstempel umzuwandeln und genau zu sehen, wie weit das Reset entfernt ist.

Im Code: reset_time - time.now() gibt die Sekunden bis zum Zurücksetzen an. Aber überprüfen Sie X-RateLimit-Remaining zuerst – wenn Sie noch Quoten haben, ist nichts zu warten.

Was die 429-Body sagt

Der 429-Statuscode allein ist nicht ausreichend. Der Antworttext gibt normalerweise an, welche Begrenzung erreicht wurde:

GitHub:

{
  "message": "API rate limit exceeded for user ID 12345.",
  "documentation_url": "https://docs.github.com/rest/overview/rate-limits"
}

Stripe:

{
  "error": {
    "code": "rate_limit",
    "message": "Too many requests hit the API too quickly.",
    "type": "invalid_request_error"
  }
}

OpenAI geht weiter: Die Fehlermeldung gibt an, ob Sie eine Begrenzung pro Minute an Token oder Anfragen erreicht haben, was Ihre Wiederholungsstrategie grundlegend verändert. Loggen Sie immer den vollständigen 429-Body.

Exponentielle Wiederholung mit Rauschen

Die naive Lösung: Fangen Sie eine 429 ein, warten Sie 1 Sekunde und versuchen Sie es erneut. Dies funktioniert aus zwei Gründen nicht:

• Wenn mehrere Worker denselben Endpoint anrufen, werden sie alle 1 Sekunde warten und gleichzeitig versuchen, es erneut zu versuchen – ein synchronisiertes Wiederholungssturm, der das Problem erneut erzeugt.
• 1 Sekunde ist sinnlos, wenn Sie eine pro-Stunde- oder pro-Tage-Begrenzung erreicht haben. Sie werden nur 3.600 weitere 429s sammeln.

Die richtige Methode ist exponentielle Wiederholung mit Rauschen: Jede Wiederholung wartet länger als die vorherige, mit einem zufälligen Komponente, um parallele Worker zu entkoppeln.

import time
import random
import requests

def fetch_with_backoff(url, headers, max_retries=5):
    base_delay = 1  # seconds

    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)

        if response.status_code != 429:
            return response

        # Prefer Retry-After if the API provides it
        retry_after = response.headers.get("Retry-After")
        if retry_after:
            wait = int(retry_after)
        else:
            # Fall back to X-RateLimit-Reset
            reset = response.headers.get("X-RateLimit-Reset")
            if reset:
                wait = max(0, int(reset) - int(time.time()))
            else:
                # Pure exponential backoff with full jitter
                cap = 60  # max wait: 60s
                wait = random.uniform(0, min(cap, base_delay * (2 ** attempt)))

        print(f"Rate limited. Attempt {attempt + 1}/{max_retries}. Waiting {wait:.1f}s")
        time.sleep(wait)

    raise Exception(f"Max retries exceeded after {max_retries} attempts")

Die Priorität in dieser Implementierung ist absichtlich geordnet:

• Retry-After zuerst — Wenn die API genau angibt, wie lange gewartet werden muss, verwenden Sie es. Warten Sie nicht mit einer eigenen Berechnung.
• X-RateLimit-Reset als Rückfalllösung — Berechnen Sie die tatsächlichen Sekunden bis zum Zurücksetzen, nicht eine feste Verzögerung.
• Vollständiges Rauschen als letzte Option — random.uniform(0, cap) verbreitet die Wiederholungen über das gesamte Wiederholungsintervall. AWSs Architekturblog dokumentiert dies als „vollständiges Rauschen“ und zeigt, dass es die Serverseitige Kollision signifikant reduziert im Vergleich zu gleichem Rauschen oder keinem Rauschen.
• max(0, ...) auf Reset — Der Reset-Timestamp kann beim Durchrechnen in der Vergangenheit sein. Schützen Sie sich vor einem negativen Wartezeitwert, der Ihr Handler abstürzt.

Gängige Fehler

Behandlung nicht-429-Fehler als Rate-Limit-Fehler. Ein 503 ist ein Serverfehler. Ein 401 bedeutet, dass Ihre Anmeldeinformationen falsch sind. Prüfen Sie status_code == 429 explizit, bevor Sie Rate-Limit-Wiederholungslogik anwenden.

Verdrängung der 429 und Rückgabe leerer Daten. Stille Fehlern sind schwerer zu debuggen als aufgefangene Ausnahmen. Stellen Sie den Fehler dar.

Verwendung einer festen Verzögerung. Wenn Sie eine pro-Stunden-Begrenzung erreicht haben und 47 Minuten auf der Uhr bleiben, bringt ein Warten von 5 Sekunden nichts. Berechnen Sie aus dem Reset-Timestamp.

Unendliche Wiederholung. Setzen Sie ein max_retries Begrenzen und erhöhen Sie nach dem Ausleeren. Einige 429-Fehler zeigen Quotenverbrauch, der erst beim nächsten Abrechnungszeitraum wiederhergestellt wird – ein unbeschränkter Wiederholungsloop ist ein Fehler.

Keine proaktive Überwachung von X-RateLimit-Remaining. Wenn Remaining fällt unter 10% von Limit, beginnen Sie, die Anfragen vor dem Erreichen von 0 zu verteilen. Die meisten SDKs tun dies nicht automatisch. Die Kosten sind einige Millisekunden zusätzlicher Latenz; der Vorteil ist, dass Sie nie eine 429 sehen werden.

Zusammenfassung

Die 429 ist kein einmaliges Problem, das Sie beheben und vergessen. Es ist ein wiederkehrendes Problem, und wenn Sie die Headers, die mit ihm kommen, ignorieren, werden Sie immer wieder derselben Wand begegnen. Verwenden Sie Retry-After wenn die API dies bereitstellt. Berechnen Sie aus X-RateLimit-Reset wenn dies nicht der Fall ist. Fügen Sie Rauschen hinzu, damit die Wiederholungen nicht synchronisiert sind. Legen Sie eine Begrenzung fest, damit unbeschränkte Wiederholungsloops keine Produktionsprobleme werden.

Und wenn Sie sich an X-RateLimit-Reset: 1716998400 und fragen, wann das tatsächlich ist – der Unix-Zeitstempel-Konverter erklärt es in einem Klick.

Das könnte Ihnen auch gefallen