Errores

Todos los errores que puede devolver la API de firma electrónica, con un código legible por máquina y estable sobre el que ramificar.

Todas las respuestas de error tienen la misma forma. Lee error.code: es un valor estable y legible por máquina. El message es para personas y puede cambiar en cualquier momento, así que nunca ramifiques según el texto del mensaje.

Forma del error

{
  "error": {
    "code": "unknown_signer_role",
    "message": "One or more recipient roles do not match this template.",
    "details": { }
  }
}

details es opcional y, cuando está presente, aporta contexto estructurado sobre el error.

Códigos de error

HTTP	`error.code`	Significado
`401`	`missing_api_key`	Falta la cabecera `X-API-Key` en la petición de token.
`401`	`invalid_api_key`	La clave es desconocida, revocada, caducada o no es de modo real.
`401`	`missing_token`	No se envió el token `Authorization: Bearer`.
`401`	`invalid_token`	El token está mal formado o caducado. Solicita uno nuevo.
`401`	`key_revoked`	La clave tras este token fue revocada o rotada: sus tokens ya no funcionan.
`403`	`insufficient_scope`	La clave no incluye el scope que requiere este endpoint.
`403`	`forbidden`	El propietario de la clave carece del permiso subyacente, o el acceso a la API no está en tu plan.
`403`	`signing_links_disabled`	El sobre no comparte enlaces de firma con el remitente.
`402`	`quota_exceeded`	No quedan solicitudes de firma por API (al enviar).
`403`	`quota_exceeded`	Se alcanzó un límite de recursos (por ejemplo, el de contactos).
`404`	`template_not_found`	No existe ninguna plantilla con ese id en tu empresa.
`404`	`envelope_not_found`	No existe ningún sobre con ese id en tu empresa.
`404`	`webhook_not_found`	No existe ninguna suscripción de webhook con ese id en tu empresa.
`422`	`unknown_signer_role`	Un rol de destinatario no coincide con la plantilla, o se proporcionó un rol bloqueado.
`422`	`sender_not_found`	`sender_email` no es un usuario activo con asiento de firma electrónica en tu empresa.
`422`	`validation_failed`	El cuerpo de la petición está mal formado o falta un campo obligatorio.
`429`	`rate_limited`	Demasiadas peticiones: espera y reintenta.
`5xx`	`send_failed`	El sobre se creó pero no pudo enviarse, así que se descartó. No se entregó nada.
`500`	`internal_error`	Algo falló de nuestro lado. Se puede reintentar.

Por qué algunos errores son deliberadamente imprecisos

En el endpoint de token, "clave inexistente", "revocada", "caducada" y "no de modo real" devuelven todos el mismo cuerpo 401. Del mismo modo, una plantilla de otra empresa y una que no existe devuelven ambas 404 template_not_found. Es intencionado: un error más específico permitiría a alguien sondear qué ids o claves existen.

Cómo gestionar bien los errores

Ramifica según error.code, nunca según message.
Reintenta 5xx, 429 y errores de red con espera progresiva. No reintentes los 4xx: la petición nos llegó y fue rechazada; corrige la petición.
Renueva ante 401 invalid_token intercambiando tu clave por un token nuevo. Si recibes key_revoked, la clave se revocó: genera una nueva en Configuración → Claves de API.
Trata quota_exceeded como una señal del plan, no como un error transitorio: se resuelve cuando el periodo se reinicia o se mejora tu plan.

Códigos de error

Cómo gestionar bien los errores

En esta página