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.

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.