Catálogo de errores¶

Todos los errores devuelven el mismo formato de cuerpo:

{
  "timestamp": "2026-08-14T15:36:00Z",
  "status": 404,
  "error": "PROCESO_NO_ENCONTRADO",
  "mensaje": "El proceso de firma indicado no existe"
}

error es el código estable — es lo que debería usar tu código para tomar decisiones (nunca parsees el texto de mensaje, ese es para mostrar a un humano y puede cambiar).

Tabla completa¶

Código	HTTP	Cuándo pasa
`CREDENCIALES_INVALIDAS`	401	Login incorrecto, sea de cliente API (`clientId`/`clientSecret`) o de usuario (`username`/`password`)
`TOKEN_INVALIDO`	401	El header `Authorization` falta, el token expiró, o está mal formado
`ACCESO_DENEGADO`	403	El token es válido, pero el rol no alcanza para ese endpoint (ej. un FIRMANTE llamando a un endpoint de ADMIN)
`PROCESO_NO_AUTORIZADO`	403	Un FIRMANTE está pidiendo/enviando a un proceso que no tiene asignado
`PROCESO_NO_ENCONTRADO`	404	El `idProcesoFirma` indicado no existe
`PROCESO_INACTIVO`	409	El proceso existe, pero está deshabilitado (por ejemplo, porque venció su certificado)
`USUARIO_YA_EXISTE`	409	El `username` ya está en uso al crear un usuario
`USUARIO_NO_ENCONTRADO`	404	El id de usuario indicado no existe
`CLIENTE_NO_ENCONTRADO`	404	El id de cliente indicado no existe
`ARCHIVO_INVALIDO`	400	Falta el PDF, el campo `pdf` no vino, el archivo no es un PDF válido, o falta algún parámetro obligatorio
`ARCHIVO_MUY_GRANDE`	413	El archivo supera el tamaño máximo permitido (25 MB)
`DOCUMENTO_NO_ENCONTRADO`	404	El `trackingId` indicado no existe
`DOCUMENTO_NO_LISTO`	409	Se pidió descargar un documento que todavía no terminó de firmarse
`DOCUMENTO_CON_ERROR`	409	El documento pasó a estado `ERROR` (ver Arquitectura y flujo)
`ERROR_INTERNO`	500	Fallo no controlado — si ves esto repetidamente, revisa los logs del servicio

Notas prácticas¶

401 vs 403: 401 siempre significa "no sé quién sos" (sin token o token inválido). 403 siempre significa "sé quién sos, pero no podés hacer esto". Nunca vas a recibir un 403 sin haber mandado un token válido primero.
PROCESO_NO_AUTORIZADO aparece en tres endpoints distintos (enviar, consultar, descargar) — siempre con el mismo significado: el proceso pedido no está en la lista de procesos asignados al FIRMANTE que hizo la llamada.
Los errores de validación de campos (falta un campo obligatorio, tipo de dato incorrecto) caen todos bajo ARCHIVO_INVALIDO con 400, incluso si no tienen que ver estrictamente con el archivo — es una simplificación deliberada del catálogo.