Manejo de errores del API - Trébol

Visión general

Todas las respuestas de error del API de Trébol siguen una estructura consistente para que puedas detectarlas y manejarlas de forma predecible en tu cliente.

Formato de respuesta de error

{
  "success": false,
  "message": "Descripción breve y accionable del error",
  "code": "CODIGO_ESTATICO",
  "timestamp": "2025-01-01T12:34:56.000Z"
}

“success”: siempre es false en los errores.
“message”: mensaje legible para humanos. No dependas únicamente de este texto para lógica.
“code”: identificador estable para programar flujos de manejo de errores.
“timestamp”: ISO 8601, útil para trazabilidad.

Programa tus clientes en función de code y del HTTP status, no del texto de message.

Códigos y estados HTTP

Código (`code`)	HTTP status	Cuándo ocurre
VALIDATION_ERROR	400	Datos inválidos o faltantes en la solicitud.
BAD_REQUEST	400	Solicitud mal formada (p.ej., parámetros requeridos ausentes).
UNAUTHORIZED	401	Falta autenticación o credenciales inválidas.
FORBIDDEN	403	Usuario autenticado sin permisos para la acción.
NOT_FOUND	404	Recurso no existe. Incluye compat. con `err_record_not_found`.
CONFLICT	409	Conflicto de estado.
DUPLICATE_RESOURCE	409	Intento de crear un recurso que ya existe.
INTERNAL_SERVER_ERROR	500	Error inesperado en el servidor.