Nopeusrajoitukset ja idempotenssi

Idempotenssi

Lähetä POST-pyynnön mukana Idempotency-Key-otsake, jotta pyynnön voi turvallisesti yrittää uudelleen. Käytä jokaiselle operaatiolle uutta, yksilöllistä arvoa (UUID tai oman järjestelmäsi tunnus, kuten onboarding-8841): 1–255 tulostettavaa ASCII-merkkiä.

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

Ensimmäinen pyyntö avaimella suoritetaan normaalisti, ja sen vastaus tallennetaan 24 tunniksi.
Uudelleenyritys samalla avaimella ja samalla pyynnöllä (metodi, polku, kysely ja runko) saa tallennetun vastauksen toistettuna otsakkeella Idempotent-Replayed: true.
Sama avain eri pyynnöllä on 422 idempotency-key-reused.
Uudelleenyritys ensimmäisen pyynnön ollessa yhä käynnissä on 409 idempotency-in-progress; yritä hetken kuluttua uudelleen.
5xx-vastauksia ei tallenneta, joten palvelinvirheen jälkeinen uudelleenyritys suoritetaan uudelleen.

Avaimet ovat kutsujakohtaisia: ne koskevat organisaatiota ja API-avainta (tai hallintapaneelin käyttäjää), joka ne lähetti. Avaimen hyväksyvät operaatiot on merkitty API-viitteeseen Idempotency-Key-otsakeparametrilla, ja niihin kuuluvat muun muassa mallien luonti, tiedostojen lataus, julkaisu, kirjekuorten luonti ja mitätöinti, linkkien uudelleenlähetys, allekirjoitusistuntojen luonti, allekirjoituslinkkien ja webhook-päätepisteiden luonti sekä tapahtumien uudelleentoimitus.

Kaksoiskappaleiden esto omalla tunnuksella

Idempotenssiavaimet suojaavat yksittäisen pyynnön uudelleenyrityksiä. Varmistaaksesi, että liiketoimintaobjekti lähetetään vain kerran, lähetä myös oma tunnuksesi ja dedupeOn:

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

Jos kirjekuori, jolla on tämä externalId, on jo olemassa (samassa tilassa), POST /v1/envelopes palauttaa sen koodilla 200 ja otsakkeella x-deduplicated: true uuden luomisen sijaan. Tämä pätee avainten, päivien ja samanaikaisten pyyntöjen yli.

Nopeusrajoitukset

Todennetulla API:lla (API-avaimet) ei nykyään ole kiinteää pyyntönopeuden rajaa; lähettämistä rajoittaa pakettisi. Rajat ovat käytössä siellä, missä väärinkäyttö on mahdollista:

Missä	Raja
`POST /v1/public/verify`	60 pyyntöä minuutissa IP-osoitetta kohden
`GET /v1/public/anchors…`, `/.well-known/bona-fide/*`	240 pyyntöä minuutissa IP-osoitetta kohden
`GET /v1/sso/discover`	30 hakua minuutissa IP-osoitetta kohden
Allekirjoittajien kertakäyttökoodit	5 koodia 15 minuutissa istuntoa kohden; 5 yritystä koodia kohden
Uudelleenlähetys vastaanottajalle	Kerran minuutissa vastaanottajaa kohden
Pysyvät linkit	Linkkikohtaisesti: `perEmailPerDay` (oletus 3), `perIpPerHour` (oletus 20), valinnainen `dailyCap`
Hallintapaneelin salasanakirjautuminen	10 minuutissa IP-osoitetta kohden; 10 15 minuutissa sähköpostiosoitetta kohden
Hallintapaneelin rekisteröityminen salasanalla	5 minuutissa IP-osoitetta kohden; 5 tunnissa sähköpostiosoitetta kohden
Salasanan palautussähköpostit	5 15 minuutissa IP-osoitetta kohden; 3 tunnissa sähköpostiosoitetta kohden
Hallintapaneelin kirjautumiskoodit	3 minuutissa IP-osoitetta kohden

Rajoitetut julkiset päätepisteet lähettävät otsakkeet RateLimit-Limit, RateLimit-Remaining ja RateLimit-Reset (sekunteina). Rajan ylittyessä API vastaa 429 ja rate-limited-ongelmalla, yleensä Retry-After-otsakkeen kanssa sekunteina.