Rate Limits & Idempotenz

Idempotenz

Senden Sie bei einem POST einen Idempotency-Key-Header mit, damit sich die Anfrage gefahrlos wiederholen lässt. Verwenden Sie pro Operation einen neuen, eindeutigen Wert (eine UUID oder eine ID aus Ihrem eigenen System wie onboarding-8841): 1 bis 255 druckbare ASCII-Zeichen.

curl https://api.bonafidesign.com/v1/envelopes \
  -H "Authorization: Bearer $BONA_FIDE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2f0e-1d0b-4c2a-9a59-3f1f1c7d2b11" \
  -d @envelope.json

Die erste Anfrage mit einem Schlüssel läuft normal, und ihre Antwort wird 24 Stunden lang gespeichert.
Eine Wiederholung mit demselben Schlüssel und derselben Anfrage (Methode, Pfad, Query und Body) erhält die gespeicherte Antwort erneut, mit dem Header Idempotent-Replayed: true.
Derselbe Schlüssel mit einer anderen Anfrage ergibt 422 idempotency-key-reused.
Eine Wiederholung, während die erste Anfrage noch läuft, ergibt 409 idempotency-in-progress; versuchen Sie es einen Moment später erneut.
5xx-Antworten werden nicht gespeichert, daher läuft eine Wiederholung nach einem Serverfehler erneut.

Schlüssel gelten pro Aufrufer: für die Organisation und den API-Schlüssel (oder Dashboard-Nutzer), der sie gesendet hat. Operationen, die einen Schlüssel akzeptieren, sind in der API-Referenz mit einem Header-Parameter Idempotency-Key gekennzeichnet, darunter das Erstellen von Vorlagen, das Hochladen von Dateien, das Veröffentlichen, das Erstellen und Stornieren von Umschlägen, das erneute Senden von Links, das Erzeugen von Signatursitzungen, das Erstellen von Signaturlinks und Webhook-Endpunkten sowie das erneute Zustellen von Events.

Deduplizierung über Ihre eigene ID

Idempotenzschlüssel schützen Wiederholungen einer einzelnen Anfrage. Um sicherzustellen, dass ein fachliches Objekt nur ein einziges Mal gesendet wird, senden Sie zusätzlich Ihre eigene ID und dedupeOn:

{ "template": "tpl_…", "externalId": "user_8841", "dedupeOn": "external_id", "…": "…" }

Existiert bereits ein Umschlag mit dieser externalId (im selben Modus), liefert POST /v1/envelopes ihn mit 200 und x-deduplicated: true zurück, statt einen weiteren zu erstellen. Das gilt über Schlüssel, Tage und gleichzeitige Anfragen hinweg.

Rate Limits

Die authentifizierte API (API-Schlüssel) hat derzeit kein festes Limit für die Anfragerate; das Senden ist durch Ihren Tarif begrenzt. Limits gelten dort, wo Missbrauch möglich ist:

Wo	Limit
`POST /v1/public/verify`	60 Anfragen pro Minute pro IP
`GET /v1/public/anchors…`, `/.well-known/bona-fide/*`	240 Anfragen pro Minute pro IP
`GET /v1/sso/discover`	30 Abfragen pro Minute pro IP
Einmalcodes für Unterzeichner	5 Codes pro 15 Minuten pro Sitzung; 5 Versuche pro Code
Erneutes Senden an Empfänger	Einmal pro Minute pro Empfänger
Dauerhafte Links	Pro Link: `perEmailPerDay` (Standard 3), `perIpPerHour` (Standard 20), optional `dailyCap`
Passwort-Anmeldung im Dashboard	10 pro Minute pro IP; 10 pro 15 Minuten pro E-Mail-Adresse
Registrierung im Dashboard mit Passwort	5 pro Minute pro IP; 5 pro Stunde pro E-Mail-Adresse
E-Mails zum Zurücksetzen des Passworts	5 pro 15 Minuten pro IP; 3 pro Stunde pro E-Mail-Adresse
Anmeldecodes für das Dashboard	3 pro Minute pro IP

Begrenzte öffentliche Endpunkte senden die Header RateLimit-Limit, RateLimit-Remaining und RateLimit-Reset (Sekunden). Oberhalb des Limits antwortet die API mit 429 und einem rate-limited-Problem, meist mit einem Retry-After-Header in Sekunden.