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:

• Starter: 30 Anfragen pro Minute
• Growth: 100 Anfragen pro Minute
• Pro: 280 Anfragen pro Minute
• Scale: 600 Anfragen pro Minute

In der Testphase gilt das Starter-Kontingent (30 Anfragen pro Minute). Jede Antwort trägt drei Header, mit denen Ihre Anwendung ihr Budget kennt:

• 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

Diese Header 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.

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.

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"