Errors and HTTP codes

factura.com.do returns business rules with a simple envelope: { success: false, message }. Authentication responds with 401 and no body, and JSON parsing errors return 400 with the default body emitted by the Minimal API binding. Learn the three shapes and every resource becomes predictable.

Summary

Business rules executed by the handler (inactive supplier, unbalanced payments, amount out of range, etc.) return 400 with { success: false, message } and a human-readable message. Authentication with X-Api-Key responds 401 with no body. JSON parsing errors are handled by the Minimal API binding: 400 with a default body, without ProblemDetails registered in the application. When the handler throws an exception, the response is { error }: 400 for argument validation, 404 for a missing resource and 500 for anything else (for example, when there is no active NCF sequence).

HTTP codes

Standard envelope

Three examples cover most cases: business rule on the body, authentication with a missing header and conflict on the resource state. The shape differs between the { success, message } envelope and the 401 with no body.

Body rule (400)

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

Unauthorized (401, no body)

HTTP/1.1 401 Unauthorized
Content-Length: 0

State conflict (400)

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

Common errors

Next steps