Errores - 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:

{
  "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.

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.

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.