429 Too Many Requests: Rate-Limits, Retry-After, Fehlalarme

Was ein 429 bedeutet und was mitkommt

429 ist in RFC 6585 als der Status für Rate-Limiting definiert: Der Client hat in einem bestimmten Zeitraum zu viele Anfragen gesendet. Die Spezifikation lässt absichtlich zwei Dinge offen: wie der Server den Client identifiziert, und wie Anfragen gezählt werden. Deshalb unterscheiden sich Rate-Limits so stark zwischen Diensten.

In der Praxis zählen Server pro IP-Adresse, pro API-Schlüssel, pro Sitzung, pro Konto, oder pro Kombination davon, und sie nutzen feste Fenster, gleitende Fenster oder Token-Buckets. Zwei identische Anfrageraten können also auf einem Endpunkt in Ordnung sein und auf einem anderen derselben Website blockiert werden.

Die Antwort trägt die Signale, die Sie brauchen:

• Retry-After ist das Standard-Signal. RFC 9110 erlaubt entweder eine Anzahl Sekunden oder ein HTTP-Datum, und ein wohlerzogener Client wartet diese Zeit ab, bevor er es erneut versucht.
• Rate-Limit-Header wie RateLimit-Limit, RateLimit-Remaining und RateLimit-Reset, oder die älteren X-RateLimit--Varianten, legen das Budget offen und wann es zurückgesetzt wird. Das sind Konventionen, kein Teil von RFC 9110, prüfen Sie also die API-Dokumentation auf die genauen Namen.
• Der Body sollte das Limit in menschenlesbaren Worten erklären. Viele APIs nennen, welches Kontingent überschritten wurde, was viel Rätselraten spart.

Ein 429 ist standardmäßig nicht cachefähig, Vermittler sollten ihn also nicht weiter ausliefern, sobald das Fenster zurückgesetzt wird.

Rate-Limit oder echter Ausfall?

Diese werden ständig verwechselt, weil beide als fehlschlagende Anfragen erscheinen. Die unterscheidenden Tests sind schnell:

• Der Code selbst. Ein Rate-Limit antwortet mit 429. Ein überlasteter oder im Wartungsmodus befindlicher Server antwortet mit 503. Beide können Retry-After tragen, weshalb Menschen sie verwechseln, aber sie bedeuten unterschiedliche Dinge: 429 sagt "Sie speziell senden zu viel", 503 sagt "der Dienst als Ganzes kann gerade keine Arbeit annehmen". Diese Seite behandelt die 503-Anleitung.
• Antwortzeit. Rate-Limits lehnen schnell ab, meist in Millisekunden, weil die Entscheidung fällt, bevor echte Arbeit passiert. Überlastung antwortet langsam oder läuft in ein Timeout.
• Wer betroffen ist. Ein Rate-Limit trifft eine Client-Identität. Testen Sie von einer anderen IP-Adresse oder mit einem anderen API-Schlüssel: Gelingt das, während der gedrosselte Client weiter fehlschlägt, ist es ein Limit, kein Ausfall.
• Das Muster über die Zeit. Rate-Limiting ist periodisch und löst sich von selbst. Fehlschläge häufen sich, hören dann genau auf, wenn das Fenster zurückgesetzt wird, und kehren zurück. Ein Ausfall nimmt seinen Betrieb nicht höflich nach Zeitplan wieder auf.
• Korrelation mit Ihrem eigenen Volumen. Begannen Fehlschläge, als Sie eine Prüfhäufigkeit erhöht, parallele Worker hinzugefügt oder einen Batch-Job gestartet haben, liegt die Ursache auf Ihrer Seite der Verbindung.

Warum Monitoring sich selbst einen 429 auslösen kann

Monitoring ist eine sich wiederholende Anfrage von einer kleinen Menge Adressen an dieselbe URL, was nahe an der Form liegt, die Rate-Limiter erfassen sollen. Ein sehr kurzes Prüfintervall macht das schlimmer, denn minütliche Prüfungen, multipliziert mit vielen überwachten URLs, summieren sich schnell gegen ein Pro-IP-Budget. Dasselbe gilt für eine Prüfung von vielen Standorten gleichzeitig: Der Ursprung sieht eine Spitze statt eines stetigen Tröpfelns, und Spitzen-Limits lösen zuerst aus.

Die Wahl der URL spielt ebenfalls eine Rolle. Suchseiten, API-Endpunkte und alles, was schreibt, sind meist härter limitiert als eine statische Startseite. Und teilen sich Monitoring und die Anwendung einen API-Schlüssel, konkurrieren beide um ein einziges Kontingent. Das Ergebnis ist ein Monitor, der die Website als fehlschlagend meldet, während die Website vollkommen gesund ist, und ein Rate-Limiter, der seine Arbeit korrekt macht.

So beheben Sie einen 429

1. Lesen Sie die Antwort-Header, bevor Sie etwas ändern:

   curl -sS -o /dev/null -D - https://example.com/api/items

   Retry-After und etwaige Rate-Limit-Header sagen Ihnen das echte Budget, was besser ist, als Intervalle zu erraten.
2. Respektieren Sie Retry-After. Sofort erneut zu versuchen verlängert die Sperre bei vielen Implementierungen. Warten Sie die genannte Zeit ab.
3. Weichen Sie exponentiell mit Jitter zurück im Client-Code, damit gleichzeitige Clients sich nicht synchronisieren und in einer Lawine erneut versuchen.
4. Senken Sie die Anfragerate. Verschieben Sie beim Monitoring einen geprüften Endpunkt auf ein längeres Intervall, oder staffeln Sie Prüfungen, sodass nicht viele Standorte in derselben Sekunde auslösen.
5. Überwachen Sie eine günstige, repräsentative URL. Ein leichtgewichtiger Health-Endpunkt oder die Startseite sagt Ihnen, dass die Website erreichbar ist, ohne das Kontingent zu verbrauchen, das Sie für echten Traffic brauchen.
6. Nehmen Sie den Monitoring-Client am Limiter aus. Setzen Sie die Prüfpunkt-Adressen auf eine Positivliste, oder geben Sie Monitoring einen eigenen API-Schlüssel mit eigenem Budget, sodass es nie mit Produktions-Traffic konkurriert.
7. Gehört Ihnen der Limiter, prüfen Sie, ob das Limit richtig ist. Fragen Sie, ob das Budget zur echten Nutzung passt, ob es pro IP ist, obwohl es pro Konto sein sollte, und ob geteilte Proxys oder Firmen-NAT viele Nutzer hinter eine Adresse bringen.

Auf 429s achten, ohne sie auszulösen

Rate-Limits erscheinen meist zuerst bei den beschäftigtsten Clients, was bedeutet, dass zahlende Kunden und Integrationen sie treffen, bevor jemand in Ihrem Team es tut. Eine geplante HTTP-Prüfung, die den erwarteten Statuscode bestätigt, zeigt einen 429 als eigenständiges, zeitgestempeltes Ereignis statt als verstreute Meldungen von "die API ist instabil", und die Zeitmessung sagt Ihnen, ob das Limit periodisch oder dauerhaft ist. Setzen Sie das Intervall mit Bedacht: oft genug, um Probleme schnell zu bemerken, sanft genug, dass die Prüfung nie das ist, was das Limit auslöst. Die breitere Familie der Ablehnungen, einschließlich 401 und 403, behandelt der 4xx-Überblick.