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 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 avec 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, rejouée avec l’en-tête Idempotent-Replayed: true.
La même clé avec une requête différente donne une erreur 422 idempotency-key-reused.
Une nouvelle tentative pendant que la première requête est toujours en cours donne une erreur 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 du serveur s’exécute donc de nouveau.

Les clés sont propres à l’appelant : l’organisation et la clé d’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, le téléversement 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 de points de terminaison 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 vous assurer qu’un objet d’affaires n’est jamais envoyé plus d’une fois, envoyez aussi votre propre identifiant et dedupeOn :

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

Si une enveloppe qui porte 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 règle vaut pour toutes les clés, sur plusieurs jours et pour les requêtes simultanées.

Limites de débit

L’API authentifiée (clés d’API) n’a pour l’instant aucune limite fixe de débit des requêtes; les envois sont limité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 par IP
`GET /v1/public/anchors…`, `/.well-known/bona-fide/*`	240 requêtes par minute par IP
`GET /v1/sso/discover`	30 recherches par minute par IP
Codes à usage unique des signataires	5 codes par 15 minutes par session; 5 tentatives par code
Renvoi aux destinataires	Une fois par minute 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 par IP; 10 par 15 minutes par adresse courriel
Inscription au tableau de bord avec mot de passe	5 par minute par IP; 5 par heure par adresse courriel
Courriels de réinitialisation du mot de passe	5 par 15 minutes par IP; 3 par heure par adresse courriel
Codes de connexion au tableau de bord	3 par minute par IP

Les points de terminaison publics limités 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.