Limites de débit et idempotence

Idempotence

Envoyez un en-tête Idempotency-Key avec une requête POST pour pouvoir la relancer sans risque. Utilisez une valeur nouvelle et unique pour chaque opération (un UUID, ou un identifiant issu de votre propre système, comme onboarding-8841) : de 1 à 255 caractères ASCII imprimables.

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

La première requête portant une clé s’exécute normalement, et sa réponse est conservée pendant 24 heures.
Une nouvelle tentative avec la même clé et la même requête (méthode, chemin, paramètres de requête et corps) reçoit la réponse conservée, avec l’en-tête Idempotent-Replayed: true.
La même clé avec une requête différente donne 422 idempotency-key-reused.
Une nouvelle tentative pendant que la première requête est encore en cours donne 409 idempotency-in-progress ; réessayez un instant plus tard.
Les réponses 5xx ne sont pas conservées : une nouvelle tentative après une erreur serveur est donc exécutée à nouveau.

Les clés sont propres à l’appelant : l’organisation et la clé API (ou l’utilisateur du tableau de bord) qui les a envoyées. Les opérations qui acceptent une clé sont signalées par un paramètre d’en-tête Idempotency-Key dans la référence de l’API, notamment la création de modèles, l’import de fichiers, la publication, la création et l’annulation d’enveloppes, le renvoi de liens, la création de sessions de signature, la création de liens de signature et d’endpoints de webhook, et la relivraison d’événements.

Dédoublonnage par votre propre identifiant

Les clés d’idempotence protègent les nouvelles tentatives d’une même requête. Pour garantir qu’un objet métier n’est jamais envoyé qu’une seule fois, envoyez aussi votre propre identifiant et dedupeOn :

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

Si une enveloppe portant cet externalId existe déjà (dans le même mode), POST /v1/envelopes la renvoie avec 200 et x-deduplicated: true au lieu d’en créer une autre. Cette garantie vaut quels que soient les clés, les jours et les requêtes simultanées.

Limites de débit

L’API authentifiée (clés API) n’applique aujourd’hui aucune limite fixe de débit de requêtes ; les envois sont bornés par votre forfait. Des limites s’appliquent là où des abus sont possibles :

Où	Limite
`POST /v1/public/verify`	60 requêtes par minute et par IP
`GET /v1/public/anchors…`, `/.well-known/bona-fide/*`	240 requêtes par minute et par IP
`GET /v1/sso/discover`	30 recherches par minute et par IP
Codes à usage unique des signataires	5 codes par tranche de 15 minutes et par session ; 5 tentatives par code
Renvoi à un destinataire	Une fois par minute et par destinataire
Liens permanents	Par lien : `perEmailPerDay` (3 par défaut), `perIpPerHour` (20 par défaut), `dailyCap` facultatif
Connexion par mot de passe au tableau de bord	10 par minute et par IP ; 10 par tranche de 15 minutes et par adresse e-mail
Inscription au tableau de bord avec mot de passe	5 par minute et par IP ; 5 par heure et par adresse e-mail
E-mails de réinitialisation du mot de passe	5 par tranche de 15 minutes et par IP ; 3 par heure et par adresse e-mail
Codes de connexion au tableau de bord	3 par minute et par IP

Les endpoints publics soumis à une limite envoient les en-têtes RateLimit-Limit, RateLimit-Remaining et RateLimit-Reset (en secondes). Au-delà de la limite, l’API répond 429 avec un problème rate-limited, généralement accompagné d’un en-tête Retry-After en secondes.