Errores

Los errores utilizan códigos de estado HTTP y un cuerpo RFC 9457 con Content-Type: application/problem+json:

{
  "type": "https://bonafidesign.com/problems/validation-error",
  "title": "Validation failed",
  "status": 422,
  "detail": "The request is invalid.",
  "errors": [
    { "pointer": "/recipients/0/email", "message": "Invalid email address" },
    { "pointer": "/recipients", "message": "Missing recipient for role 'company'." },
    { "pointer": "/recipients/1/role", "message": "Unknown role 'cfo'.", "hint": "Template roles: client, company" }
  ],
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2"
}

Miembro	Significado
type	Identificador estable: https://bonafidesign.com/problems/<slug>. Tome las decisiones en función de este valor (o del slug), no de title ni de detail
title	Resumen breve del tipo
status	El estado HTTP
detail	Explicación legible de este caso concreto
errors	Problemas de validación: pointer (un JSON Pointer al cuerpo de la petición, o a la consulta o a las variables), message y, opcionalmente, hint
requestId	También en la cabecera x-request-id. Facilítelo al servicio de asistencia
upgradeUrl	En las restricciones del plan (402, 403 plan-upgrade-required): dónde añadir una tarjeta o cambiar a un plan superior

Todos los problemas de validación de una petición se notifican a la vez, para que un cliente pueda mostrar cada uno junto al campo correspondiente.

Tipos de error

Estado	Slug	Cuándo
400	bad-request	Petición mal formada, como un cuerpo que no es JSON válido
401	unauthorized	Credenciales ausentes, mal formadas, revocadas o caducadas
402	payment-required	Un espacio de trabajo Free ha completado los sobres incluidos en este periodo; añada una tarjeta o cambie a un plan superior (el modo de prueba no se ve afectado)
403	forbidden	Autenticado, pero sin autorización: falta un permiso, una clave de API en un endpoint exclusivo del panel, una petición entre sitios
403	plan-upgrade-required	La función no está incluida en el plan del espacio de trabajo
403	verification-required	Un firmante ha enviado antes de verificar su código de un solo uso
404	not-found	El recurso no existe en su organización, o la ruta no existe
409	invalid-state	La acción no es compatible con el estado actual; por ejemplo, anular un sobre completado o generar una sesión para un destinatario que ya ha firmado
409	not-your-turn	Un firmante ha enviado antes de que terminaran los grupos de enrutamiento anteriores
409	document-mismatch	El documento ha cambiado desde que se mostró al firmante (viewedDocumentHash)
409	already-signed	La dirección de correo electrónico ya ha firmado este enlace permanente
409	in-use	Eliminación de una plantilla que utilizan sobres o enlaces de firma
409	no-draft	Publicación de una plantilla que no tiene borrador
409	idempotency-in-progress	Una petición con la misma Idempotency-Key sigue en ejecución
409	conflict	Otros conflictos
410	gone	Una sesión de firma que ya se ha utilizado o ha caducado
413	payload-too-large	Una subida que supera su límite (25 MB para los archivos de plantilla)
415	unsupported-media-type	Una subida de un tipo no admitido
422	validation-error	El cuerpo, la consulta o las variables no son válidos; consulte errors
422	idempotency-key-reused	Se ha utilizado la misma Idempotency-Key con una petición distinta
422	conversion-failed	No se ha podido convertir un documento de Word
429	rate-limited	Demasiadas peticiones; espere los segundos que indique Retry-After, si está presente
500	internal	Error inesperado. Se puede reintentar sin riesgo con la misma Idempotency-Key
501	not-implemented	La capacidad figura en el esquema, pero aún no está implementada (p. ej., los códigos por SMS)
503	converter-unavailable, billing-unavailable	Una dependencia no está disponible temporalmente; vuelva a intentarlo más tarde

Consejo

Reintente los errores 429, 5xx y de red con espera exponencial y la misma Idempotency-Key. No reintente sin cambios otras respuestas 4xx: corrija antes la petición.

Gestión de errores

const res = await fetch('https://api.bonafidesign.com/v1/envelopes', { method: 'POST', headers, body });
if (!res.ok) {
  const problem = await res.json(); // application/problem+json
  const slug = problem.type.split('/').pop();
  if (slug === 'validation-error') {
    for (const e of problem.errors) form.setError(e.pointer, e.message);
  } else if (slug === 'payment-required') {
    showUpgrade(problem.upgradeUrl);
  } else {
    throw new Error(`${problem.title} (${problem.requestId})`);
  }
}