Errores y códigos HTTP

factura.com.do retorna las reglas de negocio con un envelope simple: { success: false, message }. La autenticación responde 401 sin cuerpo y los errores de parseo de JSON devuelven 400 con el cuerpo por defecto que emite el binding de Minimal API. Aprende las tres formas y todos los recursos te resultan predecibles.

Resumen

Las reglas de negocio que ejecuta el handler (proveedor inactivo, pagos descuadrados, monto fuera de rango, etc.) devuelven 400 con { success: false, message } y un mensaje en lenguaje natural. La autenticación con X-Api-Key responde 401 sin cuerpo. Los errores de parseo de JSON los maneja el binding de Minimal API: 400 con un cuerpo por defecto, sin ProblemDetails registrado en la aplicación. Cuando el handler lanza una excepción, la respuesta es { error }: 400 si es una validación de argumentos, 404 si falta un recurso y 500 en cualquier otro caso (por ejemplo, cuando no hay una secuencia de NCF activa).

Códigos HTTP

Envelope estándar

Tres ejemplos cubren la mayoría de los casos: regla de negocio sobre el cuerpo, autenticación con cabecera faltante y conflicto sobre el estado del recurso. La forma cambia entre el envelope { success, message } y la respuesta 401 sin cuerpo.

Regla de cuerpo (400)

{
  "success": false,
  "message": "El cliente está inactivo y no puede ser utilizado en documentos."
}

No autorizado (401, sin cuerpo)

HTTP/1.1 401 Unauthorized
Content-Length: 0

Conflicto de estado (400)

{
  "success": false,
  "message": "No se puede crear un Comprobante de Compras (E41) para un proveedor registrado en la DGII."
}

Errores comunes

Siguientes pasos