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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.