> ## Documentation Index
> Fetch the complete documentation index at: https://gotrebol.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Manejo de errores del API

> Estructura de errores, códigos y ejemplos de respuestas del API de 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

```json theme={"dark"}
{
  "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.

<Tip>
  Programa tus clientes en función de `code` y del HTTP status, no del texto de `message`.
</Tip>

## 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.                               |