Límites de frecuencia e idempotencia

Idempotencia

Envíe un encabezado Idempotency-Key en una solicitud POST para poder reintentarla sin riesgo. Use 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 solicitud con una clave se ejecuta normalmente y su respuesta se almacena durante 24 horas.
Un reintento con la misma clave y la misma solicitud (método, ruta, consulta y cuerpo) recibe la respuesta almacenada, con el encabezado Idempotent-Replayed: true.
La misma clave con una solicitud diferente da 422 idempotency-key-reused.
Un reintento mientras la primera solicitud todavía se está ejecutando da 409 idempotency-in-progress; vuelva a intentarlo un momento después.
Las respuestas 5xx no se almacenan, así que un reintento después de un error del servidor se vuelve a ejecutar.

Las claves están limitadas a quien llama: la organización y la clave de API (o el usuario del panel) que las envió. Las operaciones que aceptan una clave están marcadas con un parámetro de encabezado 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.

Deduplicación por su propio ID

Las claves de idempotencia protegen los reintentos de una solicitud. Para asegurarse de que un objeto de negocio se envíe una sola 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 entre claves distintas, a lo largo de los días y con solicitudes simultáneas.

Límites de frecuencia

La API autenticada (claves de API) no tiene hoy un límite fijo de frecuencia de solicitudes; el envío está limitado por su plan. Los límites se aplican donde es posible el abuso:

Dónde	Límite
`POST /v1/public/verify`	60 solicitudes por minuto por IP
`GET /v1/public/anchors…`, `/.well-known/bona-fide/*`	240 solicitudes por minuto por IP
`GET /v1/sso/discover`	30 consultas por minuto 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 por destinatario
Enlaces permanentes	Por enlace: `perEmailPerDay` (3 de forma predeterminada), `perIpPerHour` (20 de forma predeterminada), `dailyCap` opcional
Inicio de sesión con contraseña en el panel	10 por minuto por IP; 10 cada 15 minutos por dirección de correo electrónico
Registro con contraseña en el panel	5 por minuto por IP; 5 por hora por dirección de correo electrónico
Correos de restablecimiento de contraseña	5 cada 15 minutos por IP; 3 por hora por dirección de correo electrónico
Códigos de inicio de sesión en el panel	3 por minuto por IP

Los endpoints públicos con límite envían los encabezados RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset (en segundos). Al superar el límite, la API responde 429 con un problema rate-limited, normalmente con un encabezado Retry-After en segundos.