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

# Errores

> Códigos de estado HTTP y formato de las respuestas de error de la API de Emify.

La API de Emify usa códigos de estado HTTP estándar y devuelve un cuerpo JSON consistente cuando algo falla.

## Códigos de estado

| Código                      | Significado        | Causa típica                                                                     |
| --------------------------- | ------------------ | -------------------------------------------------------------------------------- |
| `400 Bad Request`           | Solicitud inválida | Parámetros incorrectos o faltantes, o cuerpo mal formado.                        |
| `401 Unauthorized`          | No autenticado     | Falta el header `X-Api-Key` o la clave es inválida.                              |
| `403 Forbidden`             | Sin permiso        | La clave no tiene acceso al recurso solicitado.                                  |
| `404 Not Found`             | No encontrado      | El recurso no existe. Verifica la URL y los identificadores.                     |
| `422 Unprocessable Entity`  | Regla de negocio   | Los datos son válidos pero infringen una regla de negocio o del ente tributario. |
| `500 Internal Server Error` | Error del servidor | Error inesperado de Emify.                                                       |

## Formato de error

Las respuestas de error incluyen un cuerpo JSON con esta estructura:

```json theme={null}
{
  "error": "Bad Request",
  "code": "INVALID_REQUEST",
  "message": "El campo 'invoice_type' es requerido.",
  "details": ["invoice_type: must not be null"],
  "timestamp": "2026-01-15T10:30:00",
  "trace_id": "a1b2c3d4e5f6"
}
```

| Campo       | Descripción                                                     |
| ----------- | --------------------------------------------------------------- |
| `error`     | Nombre del estado HTTP.                                         |
| `code`      | Código estable del error, para manejarlo de forma programática. |
| `message`   | Descripción legible del error.                                  |
| `details`   | Lista de detalles, típicamente errores de validación por campo. |
| `timestamp` | Momento en que ocurrió el error.                                |
| `trace_id`  | Identificador de la traza, útil para el equipo de soporte.      |

<Tip>
  Maneja los errores por su `code`, no por el texto de `message`: el mensaje puede cambiar, el código no. Al reportar un problema a soporte, incluye el `trace_id`.
</Tip>

## Buenas prácticas

* Reintenta las respuestas `5xx` con backoff exponencial.
* No reintentes las respuestas `4xx` sin corregir la petición: el resultado será el mismo.
* Registra el `trace_id` y el identificador del recurso junto con la respuesta de error para facilitar el diagnóstico.