Referencia API · Errores

Errores y reintentos

Las respuestas mantienen una forma estable para que puedas centralizar el manejo de errores en tu SDK o backend.

Formato

jsonFirmARDigital API

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "La API key no tiene el permiso requerido"
  }
}

HTTPCategoríaQué hacer

400Request inválidaCorregí `data`, el tipo de archivo o los campos requeridos. No reintentes sin modificarla.

401INVALID_API_KEYVerificá que el header sea Bearer y que la clave no esté revocada.

403INSUFFICIENT_SCOPECreá una API key con el scope que solicita el endpoint.

402LIMIT_REACHEDEl workspace alcanzó el límite contratado. No hay reintento técnico que lo resuelva.

404NOT_FOUNDConfirmá el ID y que la clave sea del mismo entorno: test y live están aislados.

409SIGNER_NOT_ENROLLED o DOCUMENT_NOT_SIGNEDEsperá el estado requerido; no intentes avanzar el flujo por la fuerza.

410ENROLLMENT_EXPIREDGenerá un nuevo enrolamiento para el firmante.

422IDENTITY_REJECTEDEl flujo de identidad fue rechazado. Pedí al firmante que complete una nueva verificación.

503DOCUMENT_STORAGE_NOT_READYReintentá el GET de descarga en unos segundos; usá backoff y no recrees la sesión.

Reintentá únicamente errores de red o `503` con backoff.
Conservá la misma `Idempotency-Key` al repetir una creación.
No reintentes errores de validación sin modificar la request.
Persistí el `x-firmar-event-id` antes de procesar un webhook.
Usá la ruta de estado como reconciliación si un webhook no llegó a tu infraestructura.