Manejo de Errores

Formato de error

Cuando una petición falla, la API responde con un código HTTP 4xx o 5xx y un cuerpo JSON con el detalle en el campo error o message:

{
  "error": "descripción del error"
}

{
  "message": "descripción del error"
}

Lee primero error y, si no existe, message. Si el cuerpo no es JSON, usa el texto plano de la respuesta. Los clientes oficiales aplican esta lógica y exponen el resultado como una excepción tipada (FacturoAPIError / FacturoApiException) con el código HTTP y el cuerpo original.

Códigos HTTP

Código	Significado	Qué hacer
400	Petición inválida (estructura, campos o reglas de negocio)	Corrige los datos según el mensaje. No reintentes sin cambios.
401	API Key ausente o inválida	Verifica el header X-API-Key.
403	La API Key no tiene permiso para la operación o la empresa	Revisa los scopes de la clave y el company_id.
404	Recurso no encontrado (empresa, documento, Track ID)	Verifica los identificadores y el dgii_env.
409 / 422	Conflicto o validación de negocio (ej.: secuencia ya usada)	Revisa el mensaje; no reintentes sin cambios.
5xx	Error temporal de Facturo o de la DGII	Reintenta con backoff exponencial. Para documentos ya creados usa reintentar emisión.

Errores de red y timeouts

Los clientes oficiales usan un timeout por defecto de 30 segundos. Ante un timeout no sabes si el documento llegó a crearse: antes de volver a emitir, consulta el estado del documento para no duplicar e-NCF.

Recomendaciones

• Registra el código HTTP y el mensaje de error (nunca la API Key).
• Reintenta solo errores 5xx y de red, con un número máximo de intentos.
• Para un documento que ya tiene document_id, usa el endpoint de reintento en lugar de emitirlo de nuevo.