Rate Limits

Jedes Unternehmen hat ein Anfragebudget, das von seiner Lizenzstufe abhängt. Wird das Budget überschritten, antwortet die API mit 429 rate_limit_exceeded. Details zur Fehlerbehandlung findest du unter Fehlerbehandlung.

Lizenzstufen und Limits

Stufe	Anfragen pro Minute	Anfragen pro Tag
Basic	20	150
Premium	300	10.000

Diese Tabelle ist auch der Schlüssel zur 429-Antwort: Der Response-Body enthält plan (basic oder premium) und limit – die konkrete Zahl, an der die Anfrage gescheitert ist. Anhand der Kombination liest du ab, ob das Minuten- oder das Tageslimit gegriffen hat. Beispiel: plan: "basic" mit limit: 20 bedeutet Minutenlimit, limit: 150 bedeutet Tageslimit.

Mehr zu den Stufen und wie du Premium buchst: Lizenzstufen.

Limits gelten pro Unternehmen

Die Limits gelten pro Unternehmen, nicht pro API-Client. Legt ein Unternehmen mehrere API-Zugänge an, teilen sich alle Zugänge dasselbe Budget.

Betreust du als Integrationspartner mehrere Praxen, hat jede Praxis ihr eigenes Budget. Die Limits werden nicht über mehrere Unternehmen hinweg zusammengezählt – auch nicht, wenn deine Anfragen über eine gemeinsame IP-Adresse laufen.

Gleitendes Zeitfenster

Die Limits arbeiten mit einem gleitenden Zeitfenster, nicht mit einem festen Reset um Mitternacht. Ist das Tagesbudget aufgebraucht, kommt das Kontingent kontinuierlich zurück – bei Basic etwa eine Anfrage alle zehn Minuten.

Das bedeutet: Schöpfst du dein Tagesbudget aus, bist du nicht bis Mitternacht gesperrt, sondern für die folgenden 24 Stunden stark gedrosselt.

Rate-Limit-Header

Jede Antwort – auch bei Erfolg – enthält drei Header:

Header	Beschreibung
X-RateLimit-Limit	Das geltende Limit für die aktuelle Anfrage.
X-RateLimit-Remaining	Wie viele Anfragen im aktuellen Budget noch übrig sind.
X-RateLimit-Reset	Zeitpunkt, ab dem die nächste Anfrage wieder erlaubt ist.

Hinweis: X-RateLimit-Reset ist nicht der Zeitpunkt eines Fenster-Resets – ein gleitendes Fenster hat keine Fenstergrenze. Der Header trägt den Zeitpunkt, ab dem die nächste Anfrage erlaubt ist. Ist noch Budget übrig, liegt dieser Zeitpunkt praktisch in der Gegenwart.

Prüfe diese Header, um dein verbleibendes Budget zu kennen, statt erst bei einer 429-Antwort zu reagieren.

Ungültige Tokens: Limit pro IP-Adresse

Anfragen mit einem unbekannten oder abgelaufenen Access Token zählen nicht gegen das Unternehmensbudget. Das Gleiche gilt für Anfragen mit dem Token eines widerrufenen API-Zugangs. Sie zählen gegen ein eigenes Budget pro IP-Adresse: 1000 Anfragen pro Minute.

Ist dieses Budget aufgebraucht, antwortet die API auf jede Anfrage mit Access Token von dieser IP-Adresse mit 429 rate_limit_exceeded. Das passiert, bevor der Token geprüft wird – auch ein gültiger Token ist dann kurz gesperrt. Der Response-Body enthält nur error und error_description, kein plan und kein limit. Der Header Retry-After nennt die Wartezeit in Sekunden.

Erneuere deinen Access Token rechtzeitig, damit abgelaufene Tokens gar nicht erst Anfragen auslösen.

Empfehlungen für Massenabrufe

Bei einem Erstabgleich oder einer Vollsynchronisation kann das Tageslimit erreicht werden, bevor der Abruf abgeschlossen ist. Speichere die zuletzt verarbeitete Position und setze den Abruf dort fort, statt am nächsten Tag wieder bei offset=0 zu beginnen. Sonst kommt der Abruf nie durch.

Fordere außerdem nicht für jeden Vorgang einen neuen Access Token an. Ein Token ist eine Stunde gültig – wiederverwende ihn, statt ihn wiederholt neu anzufordern.

Token-Endpoint-Limits

Das Anfordern von Access Tokens am /api/oauth/v2/token-Endpoint wird getrennt von den übrigen API-Aufrufen begrenzt. Erfolgreiche Token-Anfragen zählen zusätzlich gegen das Unternehmensbudget der jeweiligen Lizenzstufe. Jeder Token-Versuch eines Clients zählt außerdem gegen ein eigenes, deutlich strengeres Limit – unabhängig davon, ob er erfolgreich ist oder etwa mit falschem Client-Secret oder unbekannter Client-ID scheitert.

Wenn du deinen Access Token wiederverwendest, statt ihn ständig neu anzufordern, merkst du von diesen Limits in der Praxis nichts.