Rate Limiting & Zugriffsbegrenzung – aifinyo | Billomat

Die Billomat API begrenzt die Anzahl der Anfragen pro Zeitfenster – mit dem richtigen Umgang kommst du nie ans Limit.

Was ist Rate Limiting?

Damit die Billomat-Server stabil und für alle Nutzer gleichmäßig verfügbar bleiben, ist die Anzahl der API-Anfragen pro Account und Zeitfenster begrenzt. Dieses Konzept nennt sich Rate Limiting.

Stell dir vor, du rufst in einem Call-Center an. Wenn alle gleichzeitig anrufen, ist die Leitung überlastet. Rate Limiting sorgt dafür, dass jeder seinen fairen Anteil bekommt – und verhindert, dass eine einzelne Anwendung die gesamte Kapazität blockiert.

Wie sind die Zeitfenster aufgeteilt?

Das Kontingent wird in festen 15-Minuten-Fenstern gemessen. Die Fenster sind an die Uhrzeit gebunden – nicht an den Zeitpunkt deiner ersten Anfrage:

Zeitfenster
XX:00 – XX:14
XX:15 – XX:29
XX:30 – XX:44
XX:45 – XX:59

Wichtig: Nicht verbrauchte Anfragen verfallen am Ende des Zeitfensters – sie können nicht angespart oder ins nächste Fenster übertragen werden.

Das Kontingent im Blick behalten

Jede API-Antwort enthält zwei Header, die dir deinen aktuellen Kontostand anzeigen:

Header	Bedeutung	Beispielwert
`X-Rate-Limit-Remaining`	Noch verbleibende Anfragen im aktuellen Fenster	`142`
`X-Rate-Limit-Reset`	Zeitpunkt des nächsten Fensters (Unix-Timestamp)	`1704103200`

Tipp: Überwache X-Rate-Limit-Remaining in deiner Anwendung aktiv. Nähert sich der Wert der 0, kannst du die Anfragen bewusst drosseln – bevor du einen 429-Fehler bekommst.

Was passiert bei Überschreitung?

Wenn das Kontingent erschöpft ist, antwortet die API mit dem Statuscode 429 Too Many Requests. Die Fehlermeldung enthält die genaue Wartezeit in Sekunden:

<errors>
<error>Maximum number of requests reached. Try again in 246 seconds.</error>
</errors>

Warte die angegebene Zeit ab – sofortiges Wiederholen führt nur zu weiteren 429-Fehlern und löst das Problem nicht.

Kontingent ohne registrierte App

Ohne registrierte App steht dir das tariflich zugesicherte Kontingent pro 15-Minuten-Fenster zur Verfügung. Wichtig dabei:

Mehrere Dienste oder Integrationen im selben Account teilen sich dieses Kontingent. Wenn du z.B. gleichzeitig einen Shop und ein CRM angebunden hast, zählen beide Anfragen zusammen.
Das Kontingent gilt pro Billomat-Account – nicht pro Benutzer oder API-Schlüssel.

Kontingent mit registrierter App

Wenn du eine App unter Einstellungen > Administration > Apps registrierst, erhält sie ein eigenes, höheres Kontingent – zusätzlich zum Standard-Kontingent des Accounts. Das bedeutet: Deine App konkurriert nicht mehr mit anderen Integrationen um dasselbe Budget.

Voraussetzung: X-AppId und X-AppSecret müssen bei jeder Anfrage im Header mitgeschickt werden. Mehr dazu im Artikel Authentifizierung (API-Key).

Empfehlung: Für produktive Integrationen mit regelmäßigem Datenabgleich lohnt sich die App-Registrierung immer – sie kostet nichts und erhöht das verfügbare Kontingent spürbar.

Kontingent sparen – praktische Tipps

Mit ein paar einfachen Maßnahmen kommst du deutlich weiter mit deinem Kontingent:

Webhooks statt Polling: Anstatt z.B. alle 5 Minuten zu fragen „Gibt es neue Rechnungen?", richtest du einen Webhook ein – der meldet sich von selbst, wenn etwas passiert. Webhooks verbrauchen kein API-Kontingent. Mehr dazu im Artikel Webhooks.
HEAD statt GET für Zählungen: Wenn du nur wissen möchtest, wie viele Datensätze ein Filter liefert, nutze einen HEAD-Request – er ist schneller und verbraucht trotzdem nur eine Anfrage aus dem Kontingent. Mehr dazu im Artikel Daten lesen (GET).
Maximale Seitengröße nutzen: Statt viele kleine Anfragen zu schicken, hole dir mit per_page=1000 so viele Datensätze wie möglich auf einmal.
Filter gezielt einsetzen: Lade nur die Daten, die du wirklich brauchst – z.B. ?status=OPEN statt alle Rechnungen zu holen und selbst zu filtern.
Ergebnisse cachen: Wenn sich Daten selten ändern (z.B. Artikelstammdaten), speichere sie in deiner Anwendung zwischen und frage nicht bei jedem Aufruf neu ab.

Nächste Schritte

Tools & Testing – wie du die API bequem testen kannst, bevor du loslegst
Webhooks – die effizienteste Alternative zu regelmäßigem Polling

Verknüpfung mit