Límites de frecuencia e idempotencia

Idempotencia

Envíe una cabecera Idempotency-Key en una petición POST para poder reintentarla sin riesgo. Utilice un valor nuevo y único por operación (un UUID o un ID de su propio sistema, como onboarding-8841): de 1 a 255 caracteres ASCII imprimibles.

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 primera petición con una clave se ejecuta con normalidad y su respuesta se guarda durante 24 horas.
Un reintento con la misma clave y la misma petición (método, ruta, consulta y cuerpo) recibe de nuevo la respuesta guardada, con la cabecera Idempotent-Replayed: true.
La misma clave con una petición distinta devuelve 422 idempotency-key-reused.
Un reintento mientras la primera petición sigue en ejecución devuelve 409 idempotency-in-progress; vuelva a intentarlo al cabo de un momento.
Las respuestas 5xx no se guardan, por lo que un reintento tras un error del servidor se vuelve a ejecutar.

Las claves se asocian a quien hace la llamada: la organización y la clave de API (o el usuario del panel) que las ha enviado. Las operaciones que admiten una clave están marcadas con un parámetro de cabecera Idempotency-Key en la referencia de la API; entre ellas, crear plantillas, subir archivos, publicar, crear y anular sobres, reenviar enlaces, generar sesiones de firma, crear enlaces de firma y endpoints de webhook, y volver a entregar eventos.

Eliminación de duplicados por su propio ID

Las claves de idempotencia protegen los reintentos de una petición. Para garantizar que un objeto de negocio solo se envíe una vez, envíe también su propio ID y dedupeOn:

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

Si ya existe un sobre con ese externalId (en el mismo modo), POST /v1/envelopes lo devuelve con 200 y x-deduplicated: true en lugar de crear otro. Esto se cumple con claves distintas, en días distintos y con peticiones simultáneas.

Límites de frecuencia

La API autenticada (claves de API) no tiene hoy ningún límite fijo de frecuencia de peticiones; los envíos están limitados por su plan. Los límites se aplican allí donde puede haber abusos:

Dónde	Límite
`POST /v1/public/verify`	60 peticiones por minuto y por IP
`GET /v1/public/anchors…`, `/.well-known/bona-fide/*`	240 peticiones por minuto y por IP
`GET /v1/sso/discover`	30 consultas por minuto y por IP
Códigos de un solo uso del firmante	5 códigos cada 15 minutos por sesión; 5 intentos por código
Reenvío al destinatario	Una vez por minuto y por destinatario
Enlaces permanentes	Por enlace: `perEmailPerDay` (3 por defecto), `perIpPerHour` (20 por defecto) y `dailyCap` opcional
Inicio de sesión con contraseña en el panel	10 por minuto y por IP; 10 cada 15 minutos por dirección de correo electrónico
Registro con contraseña en el panel	5 por minuto y por IP; 5 por hora y por dirección de correo electrónico
Correos de restablecimiento de contraseña	5 cada 15 minutos por IP; 3 por hora y por dirección de correo electrónico
Códigos de inicio de sesión en el panel	3 por minuto y por IP

Los endpoints públicos con límite envían las cabeceras RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset (en segundos). Si se supera el límite, la API responde 429 con un problema rate-limited, normalmente con una cabecera Retry-After en segundos.