Als Client zurückweichen: Retry-After, RateLimit-Header und Budgets pro Host

Ziel

Innerhalb der Limits eines Servers bleiben, ohne zu raten, sich von einem erreichten Limit erholen, ohne es zu verschlimmern, und verhindern, dass die vielen kleinen Anfragen eines Agenten zu einem Ausfall des Dienstes oder einer Sperre des Schlüssels werden.

Voraussetzungen

Ein Client, der Statuscodes und Header prüfen, warten und etwas Zustand pro Host führen kann. Kenntnis darüber, welche Anfragen idempotent sind.

Schritte

1. Bei 429 Too Many Requests (RFC 6585) oder 503 Service Unavailable nach Retry-After suchen. RFC 9110 definiert ihn entweder als Anzahl Sekunden oder als HTTP-Datum; entsprechend lange warten und dann einmal erneut versuchen. Ein Retry-After ist die Anweisung des Servers und überschreibt jeden lokalen Zeitplan.
2. Ohne Retry-After exponentiell ab einer Basisverzögerung mit vollem Jitter zurückweichen, die Verzögerung begrenzen und die Anzahl Versuche begrenzen. Versuche pro Anfrage zählen, nicht pro Sitzung, und nach Erreichen der Grenze mit einer klaren Fehlermeldung aufgeben.
3. Vorhandene informative Header lesen. Der IETF-Entwurf zu RateLimit-Headern definiert ein Feld RateLimit, das das verbleibende Kontingent und die Sekunden bis zum Zurücksetzen trägt, sowie ein Feld RateLimit-Policy, das die Kontingentregelung beschreibt; ein Client, der diese liest, kann bereits vor dem ersten 429 langsamer werden. Sie als Hinweise behandeln, die fehlen oder zwischen Servern unterschiedlich geformt sein können, und andernfalls auf Schritt 2 zurückfallen.
4. Ein Budget pro Host und pro Zugangsdaten führen: eine Höchstzahl gleichzeitig ausstehender Anfragen und ein Mindestintervall, bei jedem 429 nach unten und nur langsam nach oben angepasst. Parallele Agenten, die einen Schlüssel teilen, teilen sich ein Budget; über einen gemeinsamen Zähler oder eine Warteschlange koordinieren statt unabhängig voneinander zurückzuweichen.
5. Einen nicht-idempotenten Schreibvorgang nie blind wiederholen. Einen Idempotenzschlüssel anhängen, wenn die API einen unterstützt, damit ein Wiederholungsversuch nach einem Timeout den Effekt nicht verdoppelt; sonst vor dem erneuten Versuch nach dem Effekt suchen.
6. Jedes 429 mit Host, Endpunktklasse und angewandter Wartezeit protokollieren; ein Muster von 429ern auf einem Endpunkt ist ein Designsignal (weniger abrufen, mehr cachen, einen Batch-Endpunkt nutzen), kein Grund, die Wiederholungsgrenze anzuheben.
7. Für Lesevorgänge bedingte Anfragen und Caching bevorzugen: eine 304 Not Modified ist für beide Seiten günstig und wird meist nicht auf dieselbe Weise wie eine vollständige Antwort auf ein Kontingent angerechnet, was jedoch die Richtlinie des jeweiligen Servers ist.

Erwartetes Ergebnis

Limit-Treffer werden selten und selbstkorrigierend, Wiederholungsversuche verdoppeln nie einen Schreibvorgang, und der Dienst sieht einen Client, der auf Aufforderung langsamer wird, statt härter zuzuschlagen.

Grenzen und Prüfbasis

Synthese von Standards und eine vorgeschlagene Client-Disziplin; keine Messung. Der RateLimit-Header-Entwurf ist ein Entwurf: Feldnamen und Semantik können sich bis zur Veröffentlichung ändern, und viele Server senden stattdessen eigene herstellerspezifische Header.