Códigos y Formatos de Error¶

Códigos de Respuesta HTTP¶

Código	Uso
200 OK	Operación exitosa (login, listados, actualizaciones, validación TSA)
201 CREATED	Recurso creado (certificado, configuración TSA)
202 ACCEPTED	Lote de firma masiva encolado (`POST /api/firma/masiva`)
400 BAD_REQUEST	Datos faltantes/inválidos, error de negocio (`IllegalArgumentException`); en `/api/firma/*` también cubre `nivel_firma` no soportado, límites del lote excedidos, o página fuera de rango
401 UNAUTHORIZED	Token ausente/vacío, credenciales TSA inválidas, permisos insuficientes, `dni` de firma no coincide con el token
403 FORBIDDEN	Refresh token inválido o expirado; en `/api/audit/*` también cubre un usuario autenticado sin rol `ROLE_ADMIN`/`ROLE_SUPER`
404 NOT_FOUND	Alias TSA no encontrado o eliminado; en `/api/firma/` también cubre un código de solicitud masiva que no existe o no pertenece al `dni` del token; en `/api/audit/` un `dni` o `id` de proceso inexistente
408 REQUEST_TIMEOUT	Timeout contra el servicio TSA
409 CONFLICT	(`GET /api/firma/zip/{solicitud}`) la solicitud existe pero todavía no terminó de procesarse
422 UNPROCESSABLE_ENTITY	(`/api/firma/*`) el certificado principal del `dni_firmante` no existe, no está vigente, o está revocado
500 INTERNAL_SERVER_ERROR	Error no controlado
502 BAD_GATEWAY	TSA inalcanzable, respuesta vacía o error de validación TSA

Formato de Errores¶

No hay un formato de error único y estandarizado en todo el servicio. Los patrones más comunes son:

Mensaje simple (MessageResponse) — usado en Auth:

{ "message": "Error: Username is already taken!" }

Mapa con estado — usado en Certificados:

{
  "message": "Invalid file type. Please upload a .p12 file.",
  "certificate": null,
  "status": "ERROR"
}

Respuesta de firma (SignResponse) — usado en Documentos:

{
  "fileBase64Encode": null,
  "status": "ERROR",
  "message": "The file must be a PDF"
}

Validación/estado TSA (TimeStampValidationResponse o mapa {status, message, errorCode}) — usado en TSA:

{
  "status": "ERROR",
  "message": "Invalid TSA credentials.",
  "errorCode": "TSA_AUTH_FAILED",
  "alias": "tsa-prd",
  "validatedAt": "2026-02-11T15:21:01.512+00:00",
  "validationCount": 6,
  "lastValidationOk": false
}

Los errorCode de TSA están documentados en detalle en TSA.

Respuestas de /api/firma/* — siempre incluyen success (booleano) y mensaje; en error, success: false y el resto de los campos propios de cada respuesta quedan vacíos:

{ "success": false, "mensaje": "No existe un certificado principal registrado para el dni 12345678" }

Ver el detalle de cada respuesta en Firma individual y masiva.

Recomendación para integradores¶

Al consumir la API, verificar primero el código HTTP y luego, si el body trae un campo status, tratar "ERROR" como fallo aunque el HTTP status sea 200 (no todos los endpoints siguen esa convención de forma consistente).