Limits und Lastverhalten der API

Damit eine einzelne Integration die anderen nicht ausbremst, begrenzt OneSign die Zahl der API-Aufrufe. Dieser Artikel zeigt die Grenzen, woran Sie sie erkennen und wie Ihre Integration auch bei vielen Signaturen zuverlässig bleibt.

Welche Limits gelten

Gezählt wird in einem gleitenden Fenster von 60 Sekunden, je API-Schlüssel und zusätzlich je Organisation über alle Schlüssel. Es greift das Limit, das zuerst erreicht ist; eine Anfrage, die das Limit der Organisation ablehnt, zählt nicht gegen das Limit des Schlüssels. Die Werte hängen von der Stufe Ihrer Organisation ab (Standardwerte je Minute, Schlüssel / Organisation):

Team und Platform haben zusätzlich ein Fenster von einer Sekunde gegen kurze Spitzen. Ihre eigenen Werte nennt GET /v1/me (limits, je Schlüssel) und jede Antwort in der Kopfzeile RateLimit-Policy. Mehrere API-Schlüssel erhöhen das Limit der Organisation nicht. Brauchen Sie dauerhaft mehr, sprechen Sie uns an.

Woran Sie die Limits erkennen

• Ist ein Limit erreicht, antwortet die API mit 429, Fehlercode 9009 (RATE_LIMITED) und der Kopfzeile Retry-After (Sekunden). Im Fehler nennt details.violatedPolicies das überschrittene Limit, zum Beispiel sign-key.
• Sind gerade zu viele Signieraufrufe Ihrer Organisation gleichzeitig offen, kommt ebenfalls 429 / 9009, mit Retry-After: 1 und dem Limit sign-concurrent.
• Ist die Plattform oder der Signaturdienst vorübergehend überlastet oder nicht erreichbar, kommt 503 mit Fehlercode 9010 und Retry-After (bei Überlast 2 Sekunden, mit QGW-Should-Retry: true).
• In allen drei Fällen wurde nichts signiert und nichts berechnet.

Antwort 202: die Signatur läuft weiter

POST /v1/signatures antwortet in der Regel innerhalb von 25 Sekunden: mit 200 und der fertigen Signatur oder mit 202, status: WAIT_SIGN und Retry-After: 2. Eine 202 ist kein Fehler:

• Die Signatur wird im Hintergrund fertiggestellt und nie zweimal gesendet. Das Ergebnis kommt als Webhook, an Ihren callback und über GET /v1/signatures/{id}.
• Warteschlange und Frist: Ist der Signaturdienst ausgelastet oder wartet bereits eine größere Zahl von Signaturen Ihrer Organisation, wird die neue Anfrage mit 202 angenommen und hinter die wartenden eingereiht (keine Überholer). Sie wird signiert, sobald Kapazität frei ist. Die 202 nennt expiresAt und, wenn bekannt, eine geschätzte Wartezeit estimatedWaitSeconds.
• Mit expiresInSeconds (60 bis 86.400 Sekunden, Standard 900) legen Sie fest, wie lange eine Signatur warten darf; danach endet sie mit Fehler 9009 und dem Ereignis signature.failed. Senden Sie sie dann neu.
• Warten zu viele Signaturen Ihrer Organisation (Kontingent je Stufe) oder wartet die älteste zu lange, kommt sofort 429 / 9009 mit RateLimit-Policy: "backlog", Retry-After und QGW-Should-Retry: true. Dabei wird nichts angelegt und nichts berechnet; wiederholen Sie nach der Wartezeit mit demselben Idempotency-Key.
• Mit Prefer: respond-async bekommen Sie die 202 sofort. Das empfehlen wir für viele Signaturen hintereinander.
• Anfragen mit Einmalcode (certificateOtp) werden nie eingereiht, weil der Code nach kurzer Zeit abläuft. Sie bekommen bei Auslastung 429 mit Retry-After.

Den Stand fragen Sie mit GET /v1/signatures/{id} ab. Halten Sie dabei den Abstand aus Retry-After ein und fragen Sie dieselbe Signatur nicht öfter als alle paar Sekunden ab; besser sind Webhooks. Stellen Sie den Timeout Ihres HTTP-Clients auf mindestens 30 Sekunden.

Empfehlungen für Integrationen mit Volumen

• Wiederholen mit Backoff und Zufall: Wiederholen Sie nur bei 408, 429, 5xx und Netzwerkfehlern, nie bei anderen 4xx. Steht Retry-After in der Antwort, warten Sie mindestens so lange. Sonst verdoppeln Sie die Wartezeit von Versuch zu Versuch, begrenzen sie nach oben und wählen innerhalb der Grenze einen zufälligen Wert („Jitter“), damit nicht alle Ihre Prozesse im selben Takt wiederholen. Legen Sie eine Gesamtzeit fest, nach der Sie aufgeben.
• Immer mit Idempotency-Key: Senden Sie bei jedem anlegenden Aufruf (POST /v1/signatures, /v1/signature-batches, /v1/documents, /v1/verifications) einen eigenen Idempotency-Key und verwenden Sie ihn bei jeder Wiederholung unverändert. Läuft die erste Anfrage noch, kommt 409 / 9008; ist sie fertig, kommt 24 Stunden lang dieselbe Antwort ohne zweite Signatur und ohne zweite Kosten; derselbe Schlüssel mit anderem Inhalt ergibt 422 / 9008.
• Webhooks statt Abfragen: Lassen Sie sich signature.completed, signature.failed und signature_batch.completed schicken. Antworten Sie auf jede Zustellung innerhalb von 10 Sekunden mit 2xx und verarbeiten Sie den Inhalt danach. Scheitert eine Zustellung an ein Abo, wird sie bis zu 72 Stunden lang wiederholt.
• Stapel statt Einzelaufrufe: POST /v1/signature-batches nimmt standardmäßig bis zu 50 Dokumente in einem Aufruf an, antwortet mit 202 und meldet am Ende signature_batch.completed. Ein Stapel zählt einmal gegen das Limit „Signieren“, nicht je Dokument.
• Gleichmäßig senden: Verteilen Sie große Mengen über die Zeit, begrenzen Sie die Zahl gleichzeitig offener Anfragen in Ihrer Integration und bremsen Sie anhand von RateLimit-Remaining selbst, bevor Sie 429 bekommen.
• Schlüssel für Massenversand: Im Dashboard (Entwickler → API-Schlüssel → „Zustellung ändern“) stellen Inhaberin und Admins je Schlüssel ein: „Massenversand“ (priority: bulk) reiht jede Anfrage sofort mit 202 ein und sendet sie nach den interaktiven, mit einem begrenzten Teil der Kapazität; die Priorität lässt sich nur absenken. „Immer asynchron“ (asyncDefault) antwortet jeder Anfrage sofort mit 202. „Frist in der Warteschlange“ (expiresSecondsDefault, höchstens 24 Stunden) gilt, wenn die Anfrage keine eigene Frist nennt. Massenversand hat am Eingang ein eigenes Kontingent und zählt nicht gegen das Ihrer interaktiven Anfragen. GET /v1/me zeigt die Werte im Objekt apiKey; Anfragen mit Einmalcode werden nie eingereiht.