Was bedeutet ein 429 Too Many Requests und wessen Schuld ist es

Ein 429 Too Many Requests ist der einzige Statuscode, bei dem es um Sie geht und nicht um den Server oder um das, wonach Sie gefragt haben. Nichts ist kaputt, nichts fehlt, und Sie dürfen hier sein. Sie haben nur öfter gefragt, als jemand für vernünftig hielt, und die Antwort ist eine Absage mit einer Uhr daran.

Alles andere im 4xx-Bereich beschreibt eine einzelne Anfrage: diese war fehlerhaft, diese hatte keine Anmeldedaten, diese benannte nichts. Ein 429 beschreibt ein Muster. Es ist der Server, der über Ihr Verhalten über einen Zeitraum spricht, weshalb er auf eine Anfrage kommen kann, die vollkommen korrekt ist und vor zehn Minuten funktioniert hätte.

Der eine Fehler, bei dem ein neuer Versuch es schlimmer macht

Die meisten Fehler belohnen einen erneuten Versuch. Ein 503 klärt sich oft beim zweiten Anlauf, und bei einem 500 lohnt ein Reload für den Fall, dass Sie einen schlechten Moment erwischt haben. Der Instinkt hat meistens recht, und hier hat er genau unrecht.

Ein Rate Limiter zählt Anfragen. Ein erneuter Versuch ist eine Anfrage. Auf einen Dienst einzuhämmern, der Ihnen gerade gesagt hat, langsamer zu machen, verlängert das Fenster, in dem Sie festgehalten werden, und bei Diensten, die eskalieren, macht es aus einem Limit von sechzig Sekunden eine Stunde oder eine Sperre, die jemand von Hand aufheben muss. Die naive Retry-Schleife, die ohne Pause darin, ist der Weg, auf dem eine kurze Drosselung zu einem Ausfall wird, der wie die Schuld der anderen Seite aussieht.

Ein 429 ist also der Fehler, bei dem Nichtstun die aktive Entscheidung ist. Warten Sie das Fenster ab, dann versuchen Sie es noch einmal, einmal.

Die Header, die sagen, wann Sie wiederkommen sollen

Ein 429 trägt meist Retry-After und gibt entweder eine Anzahl Sekunden oder ein Datum an:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1789412400

Retry-After ist der standardisierte und der einzige, auf den Sie sich verlassen können. Die X-RateLimit-*-Familie ist Konvention statt Spezifikation: weit verbreitet, von verschiedenen Diensten verschieden geschrieben, und lesenswert, wenn sie da ist, weil sie die Form des Limits verrät und nicht nur den nächsten Moment, in dem Sie anklopfen dürfen.

Diese Header sind der Unterschied zwischen richtigem Zurückweichen und Raten. Wenn Sie irgendetwas schreiben, das nach Plan mit einer API spricht, lesen Sie sie: ein Dienst, der sechzig Sekunden gesagt hat und jede Sekunde einen Retry bekommt, wird hundertzwanzigmal gebeten, Anfragen zu bedienen, die er bereits abgelehnt hat.

Wenn der Traffic nicht Ihrer war

Das Unangenehme an einem 429 ist, dass das Gezählte selten eine Person ist. Es ist eine IP-Adresse, ein API-Key, ein Konto oder eine Session, und jedes davon deckt mehr als einen von Ihnen ab.

Ein Büro hinter einer einzigen Adresse, ein Café, ein Mobilfunkanbieter mit Carrier-Grade NAT, eine CI-Pipeline, die sich einen Key mit einem Team teilt, eine Kollegin, die ein Skript gegen denselben Endpunkt mit denselben Zugangsdaten testet. All das erzeugt einen 429 für jemanden, der nichts Ungewöhnliches getan hat, und nichts davon ist von der Fehlerseite aus sichtbar.

Daraus ergibt sich der nützliche Test. Wenn ein 429 Ihnen über Netzwerke hinweg folgt, ist es Ihr Konto oder Ihr Key, und wenn er im Mobilfunknetz verschwindet, war es die Adresse, von der Sie kamen. Das ist dieselbe Frage wie Ihren Bug von deren Ausfall zu unterscheiden, nur über ein Limit statt über einen Fehler gestellt.

Sie können gedrosselt werden, ohne je einen 429 zu sehen

Nichts verpflichtet einen Dienst, diesen Code zu nehmen. Viele geben einen 403 zurück, damit Drosselung wie eine Berechtigungsentscheidung aussieht, manche geben einen 503 zurück, weil von außen “nicht jetzt” so oder so stimmt, und ein CDN vor einer Anwendung antwortet oft mit seiner eigenen Wahl statt mit der der Anwendung.

Ein 429 ist also gewissermaßen eine gute Nachricht: es ist ein Dienst, der konkret mit Ihnen spricht. Sein Fehlen ist kein Beleg dafür, dass Sie nicht gedrosselt werden, und wenn ein 403 oder ein 503 nur unter Last und nur von einer Adresse auftaucht, ist ein Limiter das, was zu vermuten ist, ganz gleich was der Code sagt.

Wenn es Ihre API ist

Die Frage, die vor allem Tuning zu beantworten ist, lautet, welche Schicht zählt. Ein Limit in Ihrer Anwendung, eines in nginx und eines am CDN sind drei verschiedene Zahlenwerke, und das, an das Ihre Nutzer stoßen, ist meist nicht das, auf das Sie geschaut haben.

Dann senden Sie die Header. Ein 429 ohne Retry-After ist ein Dienst, der sich weigert zu sagen wann, und lässt jeden Client ein Backoff erfinden, und die erfundenen sind schlechter als die Zahl, die Sie ihnen gegeben hätten. Konkret zu sein kostet nichts.

Und achten Sie darauf, was das Limit zählt. Limits pro IP bestrafen Büros und geteilte Netze für das Verhalten einer einzigen Person darin, und das ist ein Support-Ticket, das als “Ihre Seite ist für unser ganzes Team kaputt” ankommt. Limits pro Konto oder pro Key sind schwerer umzusetzen und viel leichter zu erklären.

Warum ein 429 im Nachhinein schwer zu rekonstruieren ist

Bis Ihnen jemand davon erzählt, ist das Fenster vorbei und die Anfrage funktioniert. Was sie scheitern ließ, war nicht die Anfrage, sondern ihre Gesellschaft: die anderen neunundneunzig, die in derselben Minute ankamen, die meisten von jemand anderem, keine davon jetzt vor Ihnen.

Das Netzwerkprotokoll ist das, was einen 429 überhaupt untersuchbar macht: die fehlgeschlagene Anfrage, die genaue Minute und die Response-Header, die sagen, welches Limit getroffen wurde und wie lange es noch läuft. Das ist der Unterschied zwischen einem Bericht, den jemand gegen ein Rate-Limiter-Log halten kann, und einer Nachricht, die sagt, die Seite habe heute Morgen kurz nicht mehr funktioniert.

In einem Absatz

Ein 429 Too Many Requests bedeutet, dass Sie zu oft gefragt haben, und das macht ihn zum einzigen Statuscode, bei dem es um Ihr Verhalten geht und nicht um den Server oder die Ressource. Er ist außerdem der eine Fehler, bei dem ein erneuter Versuch aktiv kontraproduktiv ist, denn ein Retry ist eine weitere Anfrage, die der Limiter zählt: lesen Sie Retry-After, warten Sie, gehen Sie dann einmal. Der gezählte Traffic ist häufig nicht Ihrer, weil Limits für Adressen und Keys gelten, die ganze Büros und Teams abdecken, und ein Handy im Mobilfunknetz sagt Ihnen, mit welchem der beiden Sie es zu tun haben. Wenn es Ihre API ist, klären Sie, welche Schicht zählt, senden Sie immer Retry-After, und begrenzen Sie lieber einen Key als eine Adresse, damit nicht eine Person ein ganzes Gebäude aussperren kann.