API-Rate-Limits und Best Practices

Überblick

Damit die API für alle zuverlässig bleibt, begrenzt Kyvento die Anfragerate je Account. Dieser Artikel erklärt die Limits, die zugehörigen HTTP-Header und die Muster, mit denen Ihre Integration effizient und wiederholungssicher arbeitet.

Das Rate-Limit

Für API-Token-Zugriffe gilt ein Kontingent pro Account und Minute, gestaffelt nach Ihrem Tarif – wie viele Anfragen Ihr Tarif umfasst, steht auf der Tarifseite und in Ihrer Abrechnung. In der Testphase gilt das Starter-Kontingent.

Verlassen Sie sich in der Integration aber nicht auf eine feste Zahl, sondern auf die drei Header, die jede Antwort trägt:

• X-RateLimit-Limit – das Minutenkontingent Ihres Tarifs
• X-RateLimit-Remaining – verbleibende Anfragen im aktuellen Minutenfenster
• X-RateLimit-Reset – Zeitpunkt (Unix-Timestamp), zu dem wieder das volle Kontingent bereitsteht

Sie sind die verbindliche Auskunft über Ihr aktuelles Kontingent: Lesen Sie X-RateLimit-Limit zur Laufzeit aus, statt die Zahl fest in Ihre Integration zu schreiben – so bleibt Ihre Anwendung korrekt, wenn sich Ihr Tarif ändert oder die Limits angepasst werden.

Ist das Kontingent erschöpft, antwortet Kyvento mit HTTP 429, dem Fehlercode RATE_LIMITED und einem Retry-After-Header. Behandeln Sie 429 nie als Fehler Ihrer Logik, sondern warten Sie die angegebene Zeit und wiederholen Sie die Anfrage – idealerweise mit zusätzlichem Zufallsversatz, wenn mehrere Prozesse parallel arbeiten.

Zusätzliche Mengenlimits für schwere Vorgänge

Das Minutenkontingent begrenzt, wie oft Sie anfragen – nicht, wie viel ein einzelner Aufruf erzeugt. Drei besonders aufwendige Vorgänge tragen deshalb ein eigenes Kontingent. Wichtig für Integrationen: Diese Vorgänge gehören zur Anwendungsoberfläche und sind per API-Token nicht erreichbar – ein Token-Aufruf erhält HTTP 403 mit dem Fehlercode REQUIRES_INTERACTIVE_SESSION. Die folgenden Kontingente gelten daher nur für die angemeldete Browser-Sitzung:

• POST /exports/bulk-pdf – 5 pro Stunde. Der teuerste Vorgang: ein ZIP über bis zu 500 PDF-Dokumente.
• POST /exports und POST /exports/datev – 20 pro Stunde, gemeinsames Kontingent für die Export-Erzeugung.
• GET /search – 120 pro Minute, je Benutzer.

Das Tarif-Limit spielt dort keine Rolle: Es gilt ausschließlich für API-Token-Zugriffe und zählt für den ganzen Account. Anfragen aus der Browser-Sitzung laufen stattdessen unter einem eigenen Sitzungskontingent von 3000 Anfragen pro Minute je Benutzer. Auch die Suche misst je Benutzer – so kann ein Benutzer die Suche seiner Kollegen nicht lahmlegen.

Die Kontingente zählen getrennt voneinander und getrennt vom Tarif-Limit; ein erschöpftes Bulk-PDF-Kontingent blockiert also weder die Suche noch den übrigen Verkehr. Das Abrufen bereits erzeugter Exporte – Liste, Detailansicht und Download, ebenfalls nur in der Sitzung – ist nicht gedrosselt: Wer auf die Fertigstellung wartet, läuft damit nicht gegen die Erzeugungsgrenze. Wird ein Kontingent überschritten, antwortet Kyvento wie sonst auch mit 429 und einem Retry-After-Header.

Sichere Wiederholungen: der Idempotency-Key

Bricht eine schreibende Anfrage ab (Timeout, Netzfehler), wissen Sie nicht, ob sie serverseitig durchkam. Senden Sie deshalb bei kritischen POST-Anfragen den Header Idempotency-Key mit einem selbst erzeugten, eindeutigen Wert (empfohlen: UUID). Kyvento merkt sich das Ergebnis 24 Stunden: Eine Wiederholung mit demselben Key liefert die ursprüngliche Antwort, statt die Operation erneut auszuführen. Derselbe Key mit verändertem Anfrage-Inhalt wird abgelehnt – das schützt vor Programmierfehlern.

Geldbeträge in der API

Jeder Geldbetrag verlässt die API als Dezimalstring in Euro – etwa "19.90", nicht 1990 und nicht 19.9 als Zahl. Der Grund ist Genauigkeit: Produkt- und Einzelpreise erlauben mehr als zwei Nachkommastellen, die weder in Cent-Ganzzahlen noch in Gleitkommazahlen verlustfrei aufgehen. Lesen Sie die Werte deshalb in einen Dezimaltyp ein (etwa decimal.Decimal oder BigDecimal) und nicht in ein float.

Das gilt einheitlich für die v1-API, das Kundenportal und den Checkout. Eine Ausnahme beim Schreiben: Der Mindestbestellwert eines Gutscheins (minimum_order_amount) wird beim Anlegen und Ändern weiterhin als Ganzzahl in Cent erwartet, während er in der Antwort als Dezimalstring erscheint. Übernehmen Sie den gelesenen Wert also nicht unverändert in ein Schreib-Payload.

Pagination richtig nutzen

• Listen liefern data plus meta mit per_page, has_more und Folgeseiten-Informationen.
• per_page akzeptiert bis zu 1000 Einträge – für Massenabgleiche große Seiten wählen, das spart Anfragen aufs Kontingent.
• Für große, sich ändernde Bestände empfiehlt sich die Cursor-Pagination (?pagination=cursor): Sie blättern über meta.next_cursor stabil weiter, auch wenn parallel Datensätze entstehen oder verschwinden.

Best Practices für sparsame Integrationen

1. Webhooks statt Polling: Lassen Sie sich Änderungen per Webhook melden, statt Listen im Minutentakt abzufragen – das ist schneller und verbraucht praktisch kein Kontingent (siehe Webhooks konfigurieren).
2. Budget beobachten: Loggen Sie X-RateLimit-Remaining und drosseln Sie Batch-Jobs, bevor das Limit greift.
3. Exponentiell zurückweichen: Bei 429 und 5xx mit wachsenden Abständen wiederholen – nie in einer engen Schleife.
4. Fehler maschinenlesbar auswerten: Verzweigen Sie auf den error_code der Antwort, nicht auf Meldungstexte.
5. Massenabgleiche entzerren: Große Synchronisationen über die Zeit verteilen, statt das Minutenkontingent in kurzen Spitzen auszuschöpfen – so bleibt Budget fürs parallele Tagesgeschäft frei.

Nächste Schritte

• Alle Endpunkte und Konventionen – siehe API-Dokumentation und Beispiele
• Push-Benachrichtigungen einrichten – siehe Webhooks konfigurieren