RateLimit und RateLimit-Policy gegenüber X-RateLimit-*: Quota-Header einer API lesen, egal welche sie sendet

Worum es geht

RFC 9110 definiert für diesen Zweck genau einen standardisierten, tragenden Header: «the Retry-After field value can be either an HTTP-date or a number of seconds to delay after receiving the response», formal Retry-After = HTTP-date / delay-seconds. RFC 9110 beschreibt seine Bedeutung bei 503- und 3xx-Antworten, und RFC 6585 erlaubt ihn bei einer 429-Antwort. Er gibt an, wie lange der Client warten soll («ought to wait»); es ist die Vorgabe des Servers, keine clientseitige Schätzung. Davon unabhängig schlägt ein aktiver IETF-Internet-Draft, draft-ietf-httpapi-ratelimit-headers (zum Zeitpunkt des Schreibens Revision -11), zwei informative Felder vor, die vor einer Drosselung der Anfragen eingesetzt werden: RateLimit-Policy beschreibt das Kontingent (zum Beispiel RateLimit-Policy: "default";q=100;w=60, also 100 Anfragen pro 60-Sekunden-Fenster unter einer Policy namens «default»), und RateLimit meldet das unter dieser Policy aktuell verfügbare Kontingent (zum Beispiel RateLimit: "default";r=50;t=30: 50 Kontingenteinheiten verfügbar, zu nutzen innerhalb eines effektiven Fensters von 30 Sekunden). Der Draft weist darauf hin, dass das effektive Fenster «does not imply anything about when the server will increase the available quota»; t ist also kein Zeitpunkt für das Zurücksetzen. Es handelt sich weiterhin um einen Entwurf: Ein Internet-Draft ist nach dem IETF-Verfahren «valid for a maximum of six months» und eignet sich nicht als stabile Referenz, sodass sich die genaue Feldsyntax vor einer Veröffentlichung noch ändern kann. In der Praxis sind die meisten produktiven APIs älter als dieser Draft oder ignorieren ihn und senden stattdessen eigene Header mit Namen wie x-ratelimit-limit, x-ratelimit-remaining und x-ratelimit-reset (die REST-API von GitHub ist ein dokumentiertes Beispiel). Deren Form regelt der Draft nicht, und sie unterscheidet sich je nach Anbieter.

Warum es wichtig ist

Ein generischer Client, der viele APIs anbindet, begegnet allen drei Situationen: einem informativen Header auf dem Standards-Track, einem herstellerspezifischen Ad-hoc-Header oder nichts ausser Retry-After bei der schliesslich eintreffenden 429-Antwort. Er braucht deshalb eine Rückfallreihenfolge, die nicht voraussetzt, dass einer dieser Header vorhanden ist.

So wird es angewendet

• Retry-After als massgeblich behandeln, wann immer es vorhanden ist, bei jedem Statuscode, der es mitführt; beide Formen (ganzzahlige Sekunden und HTTP-date) auswerten und vor dem erneuten Versuch mindestens so lange warten.
• Sind RateLimit/RateLimit-Policy vorhanden, diese defensiv parsen (es ist ein Entwurf: Feldnamen, Trennzeichen und sogar die Header-Namen haben sich über die Draft-Revisionen geändert) und damit die Anfragerate drosseln, bevor das Kontingent null erreicht.
• Erscheinen nur herstellerspezifische Header im Stil von x-ratelimit-*, ihr Vorhandensein und ihre Bedeutung als spezifisch für diese API betrachten; nicht annehmen, dass gleiche Feldnamen bei einem anderen Anbieter dasselbe bedeuten.
• Fehlt alles Genannte, bei 429/503 auf exponentielles Backoff mit Jitter zurückfallen, da RFC 9110 überhaupt keinen informativen Header verlangt.

Stolpersteine

Einen Parser fest auf die aktuelle Draft-Syntax von RateLimit/RateLimit-Policy auszulegen und sie wie einen fertigen Standard zu behandeln; der Draft warnt ausdrücklich davor, ihn zu zitieren «as reference material... other than as work in progress.» Ebenso ein Fehler: einen Retry-After-Wert zu ignorieren, weil ein informativer Header mehr verbleibendes Kontingent nahelegte. Retry-After gibt wieder, was der Server tatsächlich entschieden hat, und das kann von einer zuvor gesendeten informativen Schätzung abweichen.