Rate limits & idempotentie

Idempotentie

Stuur een Idempotency-Key-header mee bij een POST om die veilig opnieuw te kunnen proberen. Gebruik per operatie een nieuwe, unieke waarde (een UUID, of een id uit uw eigen systeem zoals onboarding-8841): 1 tot 255 afdrukbare ASCII-tekens.

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

Het eerste request met een key wordt normaal uitgevoerd en het antwoord wordt 24 uur bewaard.
Een nieuwe poging met dezelfde key en hetzelfde request (methode, pad, query en body) krijgt het bewaarde antwoord opnieuw, met de header Idempotent-Replayed: true.
Dezelfde key met een ander request geeft een 422 idempotency-key-reused.
Een nieuwe poging terwijl het eerste request nog loopt, geeft een 409 idempotency-in-progress; probeer het even later opnieuw.
5xx-antwoorden worden niet bewaard, dus een nieuwe poging na een serverfout wordt opnieuw uitgevoerd.

Keys gelden per caller: de organisatie en de API-key (of dashboardgebruiker) die ze heeft verstuurd. Operaties die een key accepteren, zijn in de API-naslag gemarkeerd met een headerparameter Idempotency-Key, waaronder sjablonen aanmaken, bestanden uploaden, publiceren, enveloppen aanmaken en intrekken, links opnieuw versturen, ondertekeningssessies aanmaken, ondertekeningslinks en webhook-endpoints aanmaken en events opnieuw bezorgen.

Ontdubbeling op uw eigen id

Idempotency keys beschermen nieuwe pogingen van één request. Om zeker te weten dat een zakelijk object maar één keer wordt verstuurd, stuurt u ook uw eigen id en dedupeOn mee:

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

Als er al een envelop met die externalId bestaat (in dezelfde modus), geeft POST /v1/envelopes die terug met 200 en x-deduplicated: true in plaats van een nieuwe aan te maken. Dat geldt over keys, dagen en gelijktijdige requests heen.

Rate limits

De geauthenticeerde API (API-keys) heeft op dit moment geen vaste limiet op het aantal requests; versturen wordt begrensd door uw abonnement. Limieten gelden waar misbruik mogelijk is:

Waar	Limiet
`POST /v1/public/verify`	60 requests per minuut per IP-adres
`GET /v1/public/anchors…`, `/.well-known/bona-fide/*`	240 requests per minuut per IP-adres
`GET /v1/sso/discover`	30 opzoekingen per minuut per IP-adres
Eenmalige codes voor ondertekenaars	5 codes per 15 minuten per sessie; 5 pogingen per code
Opnieuw versturen naar een ontvanger	Eén keer per minuut per ontvanger
Permanente links	Per link: `perEmailPerDay` (standaard 3), `perIpPerHour` (standaard 20), optioneel `dailyCap`
Inloggen op het dashboard met wachtwoord	10 per minuut per IP-adres; 10 per 15 minuten per e-mailadres
Registreren voor het dashboard met wachtwoord	5 per minuut per IP-adres; 5 per uur per e-mailadres
E-mails voor wachtwoordherstel	5 per 15 minuten per IP-adres; 3 per uur per e-mailadres
Inlogcodes voor het dashboard	3 per minuut per IP-adres

Openbare endpoints met een limiet sturen de headers RateLimit-Limit, RateLimit-Remaining en RateLimit-Reset (seconden). Boven de limiet antwoordt de API met 429 en een rate-limited-probleem, meestal met een Retry-After-header in seconden.