API-Limits und Throttling: So stoßen Sie nicht an die Grenze

Eine Integration, die im Test mit einem Dutzend Anfragen einwandfrei lief, beginnt unter realer Last Ablehnungen zu erhalten. Die Ursache ist keine Störung der API, sondern ein Anfragetempo, das den zulässigen Schwellenwert überschritten hat. Wir klären, wozu Limits überhaupt existieren, wie Sie sie von einem Dienstausfall unterscheiden, wie Sie die Last auf Ihrer Seite glätten und warum eine Statusabfrage im Sekundentakt das Ergebnis in der Regel nicht beschleunigt.

Warum Dienste die Anfragefrequenz begrenzen

Ein Limit schützt die gemeinsame Infrastruktur: Ohne Begrenzung könnte ein einzelner Kunde mit einem aggressiven Skript Ressourcen belegen, die alle anderen benötigen. Zugleich sorgt es für eine faire Verteilung der Kapazität – ein Schwellenwert pro Konto stellt sicher, dass die Integration eines anderen Nutzers nicht die Bandbreite aufbraucht, die Sie bezahlt haben. Wenn Sie an dieses Limit stoßen, sieht das konkret so aus: Der Dienst antwortet mit dem Code 429 und liefert häufig einen Header mit der empfohlenen Pause vor dem nächsten Versuch mit. Das unterscheidet sich grundlegend von einem Ausfall des Dienstes – bei einer Störung erhalten alle Kunden durchgehend Fehler, und zwar bei ganz unterschiedlichen Operationen, während das Throttling gezielt Ihren Schlüssel trifft, und zwar wegen seines Anfragetempos. Wenn die Antwort einen eindeutigen Code für die Begrenzung enthält, ist die Infrastruktur intakt und arbeitet normal – das Problem liegt in der Geschwindigkeit, mit der Sie anklopfen, nicht im Dienst.

Gleichmäßiges Tempo statt Lastspitzen

Viele Limits werden pro Zeitfenster berechnet – pro Sekunde oder pro Minute. Wenn Sie hundert Anfragen in einem Schwung senden und danach pausieren, ist der Zähler des Fensters sofort erschöpft, obwohl die durchschnittliche Last über eine Stunde bescheiden sein kann. Die Begrenzung reagiert auf die Spitze, nicht auf den Durchschnitt. Dasselbe Arbeitsvolumen, gleichmäßig innerhalb des Fensters verteilt, läuft ohne eine einzige Ablehnung durch. Beim Glätten des Tempos geht es nicht darum, weniger Anfragen zu stellen, sondern darum, sie nicht auf einen kurzen Zeitraum zu konzentrieren.

Warteschlange und Begrenzung paralleler Threads auf Ihrer Seite

Aufgaben in einer Anwendung entstehen selten gleichmäßig: Ein ganzer Stapel Arbeit kann auf einmal eintreffen – etwa nach einem Datenimport oder einer Massenaktion eines Nutzers. Wenn jede Aufgabe sofort eine Anfrage an die API auslöst, wird die Spitze auf Ihrer Seite zur Spitze an der Dienstgrenze. Eine Warteschlange mit kontrollierter Abgaberate löst diese Entkopplung: Die Aufgaben sammeln sich in der Warteschlange, und nach außen geht ein gleichmäßiger Strom von Anfragen. Zusätzlich sollten Sie die Zahl paralleler Verbindungen zur API begrenzen – selbst mit Warteschlange erzeugen zehn Threads, die gleichzeitig auf einen frequenzbegrenzten Endpunkt zugreifen, dieselbe Spitze wie ein ungebremster einzelner Thread.

Statusabfrage und Pause bei Ablehnung

Eine Statusabfrage im Sekundentakt ist fast immer überflüssig: Das Ergebnis erscheint nicht schneller, nur weil Sie öfter danach fragen. Eine reale Operation – die Zustellung einer SMS, das Anlegen eines Ports, die Verarbeitung einer Zahlung – ist durch das Netzwerk und die interne Warteschlange des Dienstes selbst begrenzt, und Abfragen in kürzeren Abständen als dieser natürlichen Dauer verbrennen lediglich Kontingent, ohne die Antwort näher zu bringen. Ein sinnvolles Abfrageintervall orientiert sich an der typischen Ausführungszeit der Operation und nicht am Wunsch, das Ergebnis sofort zu sehen.

Wenn Sie wegen des Limits abgelehnt wurden, wiederholen Sie die Anfrage nicht sofort im gleichen Tempo – das verlängert die Sperre garantiert. Die richtige Reaktion ist eine exponentielle Pause: Jeder weitere Versuch wartet länger als der vorherige, zum Beispiel eine Sekunde, dann zwei, vier, acht. Wenn der Dienst einen Header mit der empfohlenen Wartezeit zurückgegeben hat, richten Sie sich danach und nicht nach Ihrer eigenen Schätzung.

Getrennte Limits pro Schlüssel und Überwachung der Schwelle

Ein Limit ist fast immer an einen Schlüssel oder ein Konto gebunden und nicht an den Dienst insgesamt. Wenn eine Hintergrundsynchronisation und ein Nutzerszenario denselben API-Schlüssel verwenden, kann eine schwere Hintergrundaufgabe das gesamte Kontingent aufzehren und den normalen Nutzer ohne Antwort lassen. Verschiedene Schlüssel für verschiedene Aufgaben ergeben verschiedene Zähler – genau dasselbe Trennungsprinzip wie bei der Proxy-API. Außerdem sollten Sie den Kontingentverbrauch proaktiv beobachten: Viele APIs liefern in der Antwort das Restkontingent mit, und anhand dessen sehen Sie im Kundenkonto, dass Sie sich der Schwelle nähern, bevor die Ablehnungen beginnen – und nicht erst nach dem ersten 429.

Häufig gestellte Fragen

Kann man das Limit für ein bestimmtes Konto erhöhen?

Bei einem Teil der Dienste wächst das Limit mit dem Tarif oder auf gesonderte Anfrage beim Support unter Beschreibung des Lastszenarios. Darauf sollten Sie sich vorab nicht verlassen – die Integration sollte besser für die aktuelle Schwelle ausgelegt werden, und eine Erweiterung gilt als Bonus, nicht als Plan.

Warum kommt 429 auch bei geringem Anfragetempo?

Eine häufige Ursache ist ein gemeinsamer Schlüssel mit einem anderen Prozess, der bereits einen Teil des Kontingents verbraucht. Die zweite: Das Limitfenster ist kürzer, als es scheint – das durchschnittliche Tempo pro Minute ist niedrig, aber innerhalb einer Sekunde treten Spitzen auf. Prüfen Sie beide Varianten, bevor Sie die Logik der Integration selbst ändern.

Gilt das Limit für alle API-Methoden gleichermaßen?

In der Regel nicht: Aufwendige Operationen wie Suchen oder Massenabfragen sind strenger begrenzt als eine einfache Statusprüfung. Maßgeblich ist die Limittabelle für die jeweiligen Methoden in der Dokumentation, nicht eine einzige allgemeine Zahl.

Die genauen Limitwerte, Fehlercodes und Header mit der Pause vor dem Wiederholungsversuch finden Sie in der Dokumentation der OTP API.