Was ist API-Ratenbegrenzung?

API-Ratenbegrenzung beschränkt die Anfragen, die ein Client innerhalb eines festgelegten Zeitraums oder Ressourcenbudgets stellen darf. Ein Dienst kann Limits pro Konto, Zugangsdaten-Eintrag, Endpunkt, Adresse oder anderer Nutzungsgrenze anwenden.

Ein Ratenbegrenzer zählt Anfragen oder gewichtete Kosten pro Anfrage gegen ein Kontingent, das einer Partition wie einem Konto, einem Zugangsdaten-Eintrag, einer IP-Adresse oder einem Endpunkt zugeordnet ist. Für dieselbe Anfrage können mehrere Regeln gelten. Der Zählalgorithmus bestimmt, wie Anfragespitzen behandelt werden. Ein Zähler mit festem Zeitfenster wird an jeder Fenstergrenze zurückgesetzt. So kann ein Client das Kontingent eines Fensters kurz vor dem Zurücksetzen und das des nächsten kurz danach ausschöpfen. Ein gleitendes Zeitfenster glättet diesen Übergang, etwa indem es den Zählerstand des vorherigen Fensters entsprechend dessen verbleibender Überlappung gewichtet hinzurechnet. Ein Token-Bucket füllt sich mit konstanter Rate bis zu einer festen Kapazität mit Tokens. Diese Kapazität begrenzt die zulässige Anfragespitze. Ein Leaky-Bucket leert sich mit konstanter Rate; die Implementierung von NGINX verzögert überschüssige Anfragen standardmäßig und weist sie zurück, sobald sie die konfigurierte Spitzengröße überschreiten. Ein Dienst kann mehrere Begrenzer parallel einsetzen, etwa für die Anfragerate, die Anzahl gleichzeitiger Anfragen und ein separates Budget für aufwendige oder inhaltserzeugende Vorgänge. Unter einem Limit zu bleiben bedeutet daher nicht, alle Limits einzuhalten. Wird eine Anfrage zurückgewiesen, kann die Antwort eine Wartezeit angeben. So können Clients ihre Retries zeitlich verteilen, statt alle gleichzeitig erneut anzufragen.

HTTP definiert den Status 429 Too Many Requests für eine Anfrage, die einer Ratenbegrenzung unterliegt. Die Antwort kann einen Header namens Retry-After enthalten, doch beides ist nicht garantiert. GitHub dokumentiert, dass es mit 403 oder 429 antworten kann, zusammen mit einem Header namens x-ratelimit-remaining mit dem Wert 0 oder einer Fehlermeldung, dass ein Ratenlimit überschritten wurde. Das Modul limit_req von NGINX weist Anfragen mit 503 zurück, sofern limit_req_status nicht gesetzt ist. Erkennen Sie eine Drosselung anhand der Statuscodes, Header und des Fehlerantwortkörpers, die die API dokumentiert, nicht allein anhand von 429.
Retry-After ist entweder eine Anzahl von Sekunden, die nach Empfang der Antwort zu warten sind, oder ein HTTP-Datum. Ein Client muss daher beide Formen parsen. Manche APIs geben die Wartezeit an anderer Stelle an: GitHub verwendet auch x-ratelimit-reset, einen Zeitpunkt in UTC-Epochensekunden, und andere Dienste nennen eine Verzögerung im JSON-Fehlerantwortkörper. Lesen Sie die Wartezeit an der Stelle und in der Einheit aus, die die API dokumentiert.
Es gibt keinen abgeschlossenen Standard zur Bekanntgabe des verbleibenden Kontingents. Die Header-Felder RateLimit und RateLimit-Policy sind Gegenstand eines IETF-Internet-Drafts (Revision 11 vom Mai 2026), kein RFC. Bereits eingesetzte APIs verwenden anbieterspezifische Namen wie x-ratelimit-remaining. Der Entwurf weist Clients an, das angegebene Kontingent nicht als Garantie zu behandeln, und räumt Retry-After Vorrang ein, wenn eine Antwort beides enthält.
Das gemeldete Kontingent kann ungenau sein, da Begrenzer, die auf vielen Servern laufen, ihre Zählerstände teilen oder annähern. GitHub weist darauf hin, dass die verbleibende Anzahl zwischen Antworten abweichen kann, wenn Anfragen in mehreren Regionen verarbeitet werden, und rät von Logik ab, die von einer exakten verbleibenden Anzahl abhängt. Amazon API Gateway beschreibt seine Drosselungen und Kontingente als Best-Effort-Zielwerte, nicht als garantierte Obergrenzen. Passen Sie das Anfragetempo anhand der gemeldeten Werte an, behandeln Sie aber weiterhin Antworten wegen Limitüberschreitung, auch wenn die letzte Antwort noch ein Restkontingent auswies.

Ratenlimits prägen jeden Client, der Anfragen in großer Zahl oder parallel sendet, etwa bei Importen, Polling-Schleifen, Batch-Aufträgen und Retry-Logik. Ermitteln Sie vor der Entwicklung des Clients die dokumentierten Limits der API und ihre Antwort bei einer Limitüberschreitung. Warten Sie dann mindestens so lange, wie diese Antwort vorgibt, fügen Sie Zufallsstreuung hinzu, damit parallele Worker nicht alle gleichzeitig erneut anfragen, und begrenzen Sie die Anzahl der Versuche. Nennt eine Antwort wegen Limitüberschreitung keine Wartezeit, verwenden Sie die von der API dokumentierte Ausweichstrategie. Fehlt auch diese, verwenden Sie eine Verzögerung, die mit jedem Versuch exponentiell bis zu einem Höchstwert wächst. Sofortige erneute Versuche erhöhen die Last und können die Drosselung verlängern. Einige Anbieter, darunter GitHub, warnen, dass eine Integration gesperrt werden kann, wenn sie während einer Drosselung weiterhin Anfragen sendet.

Transloadit begrenzt die Anfragerate seiner eigenen API und dokumentiert die aktuellen Limits auf seiner Seite zur Ratenbegrenzung. Wird eine Anfrage wegen Überschreitung eines Erstellungs- oder Parallelitätslimits zurückgewiesen, enthält die JSON-Fehlerantwort eine empfohlene Wartezeit in Sekunden. Die offiziellen SDKs von Transloadit berücksichtigen diesen Backoff bereits und versuchen es danach erneut.

Die angegebene Wartezeit ist eine Backoff-Empfehlung: Laut Dokumentation garantiert sie nicht, dass nach ihrem Ablauf Kapazität verfügbar ist. Dieselbe Seite beschreibt ein separates Limit für hohe Anfragefrequenzen. Die dafür gezeigte Antwort enthält keine Wartezeit, daher muss ein Client, der sie verarbeitet, eine eigene Backoff-Verzögerung vorsehen.

Entdecken Sie die Plattformfunktionen von Transloadit

Was ist API-Ratenbegrenzung?

So funktioniert API-Ratenbegrenzung

Wichtige Fakten

Wann API-Ratenbegrenzung wichtig ist

So hilft Transloadit bei der API-Ratenbegrenzung

Quellen

Machen Sie aus Medienwissen eine funktionierende Pipeline