Errores

Los errores usan 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>. Base su lógica en este valor (o en el slug), no en title ni en 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 solicitud, o a la consulta o a las variables), message y, opcionalmente, hint
requestId	También en el encabezado x-request-id. Indíquelo al soporte
upgradeUrl	En las restricciones del plan (402, 403 plan-upgrade-required): dónde agregar una tarjeta o mejorar el plan

Todos los problemas de validación de una solicitud se informan 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	Solicitud con formato incorrecto, como un cuerpo que no es JSON válido
401	unauthorized	Credenciales ausentes, con formato incorrecto, revocadas o vencidas
402	payment-required	Un espacio de trabajo Free completó sus sobres incluidos en este período; agregue una tarjeta o mejore el plan (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 solicitud entre sitios
403	plan-upgrade-required	La función no está incluida en el plan del espacio de trabajo
403	verification-required	Un firmante envió 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 corresponde al estado actual; por ejemplo, anular un sobre completado o generar una sesión para un destinatario que ya firmó
409	not-your-turn	Un firmante envió antes de que terminaran los grupos de enrutamiento anteriores
409	document-mismatch	El documento cambió desde que se le mostró al firmante (viewedDocumentHash)
409	already-signed	La dirección de correo electrónico ya firmó este enlace permanente
409	in-use	Eliminación de una plantilla que usan sobres o enlaces de firma
409	no-draft	Publicación de una plantilla que no tiene borrador
409	idempotency-in-progress	Una solicitud con la misma Idempotency-Key todavía se está ejecutando
409	conflict	Otros conflictos
410	gone	Una sesión de firma que ya se usó o que venció
413	payload-too-large	Una carga que supera su límite (25 MB para los archivos de plantilla)
415	unsupported-media-type	Una carga 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 usó la misma Idempotency-Key con una solicitud diferente
422	conversion-failed	No se pudo convertir un documento de Word
429	rate-limited	Demasiadas solicitudes; espere los segundos que indique Retry-After cuando esté presente
500	internal	Error inesperado. Se puede reintentar sin riesgo con la misma Idempotency-Key
501	not-implemented	La capacidad existe en el esquema, pero todavía no está implementada (p. ej., 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: primero corrija la solicitud.

Manejo 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})`);
  }
}