--- title: "Errors and HTTP codes" description: "Standard { success, message } envelope and the HTTP code table the API returns." canonical: https://factura.com.do/en/desarrolladores/errores lang: en generator: factura.com.do docs-index --- Conventions # 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 | Code | When it occurs | Expected action | | ------------------------- | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | | 200 OK | GET with result or POST/PUT/DELETE processed. Void and DELETE also respond 200 when they fail, with success: false | Read success before assuming the operation took effect | | 400 Bad Request | Malformed JSON, body validation or failed business rule | Read message and fix the body | | 401 Unauthorized | X-Api-Key is missing or invalid | Rotate or renew the key | | 403 Forbidden | The key is valid, but the workspace is not on the Corporativo plan | Move to the Corporativo plan | | 404 Not Found | id does not exist in your workspace, or the note references a sequence that does not exist | Verify the resource belongs to the tenant | | 500 Internal Server Error | Unhandled exception, such as creating a document with no active NCF sequence | Read error; if it is the sequence, set it up in the app. Otherwise retry with backoff and open a ticket if it persists | ## 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) 400-business-rule.json ``` { "success": false, "message": "El cliente está inactivo y no puede ser utilizado en documentos." } ``` ### Unauthorized (401, no body) 401-unauthorized.txt ``` HTTP/1.1 401 Unauthorized Content-Length: 0 ``` ### State conflict (400) 400-state-conflict.json ``` { "success": false, "message": "No se puede crear un Comprobante de Compras (E41) para un proveedor registrado en la DGII." } ``` ## Common errors | Case | Code | Detail | | ---------------------------------------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------- | | Subdomain that matches no workspace | 404 | No body | | X-Api-Key missing or expired | 401 | No body. Retry with the correct header | | Workspace without the Corporativo plan | 403 | El acceso a la API REST está disponible solo en el plan Corporativo. | | No active NCF sequence for the type | 500 | No hay secuencia activa para el tipo de documento N | | Credit or debit note with a non-existent referenceSequence | 404 | No se encontró un documento con la secuencia 'E310000000001'. | | DELETE of a customer that does not exist | 200 | success: false · CustomerId with ID … not found. | | Voiding a document the DGII is still validating | 200 | success: false · Error al anular factura: No se puede anular una factura que está en proceso de validación por la DGII. … | | customerId or another id does not exist in the workspace | 404 | No body (resource not found) | | Inactive supplier in the catalog | 400 | El proveedor está inactivo y no puede ser utilizado en documentos. | | E41 with a DGII-registered supplier | 400 | No se puede crear un Comprobante de Compras (E41) para un proveedor registrado en la DGII. | | Payments do not balance with the document total | 400 | La suma de los pagos (RD$ X) no coincide con el monto total del documento (RD$ Y). | | edit-amount with a proposed amount exceeding the original | 400 | El monto propuesto (RD$ X) no puede exceder el total del documento original (RD$ Y). | | Malformed JSON or unexpected type | 400 | Response from the Minimal API binder; the exact shape depends on the ASP.NET Core version. | Parameterized messages arrive with formatted amounts The details showing `RD$ X` and `RD$ Y` above are illustrative: the backend interpolates the real figures using the `en-US` culture currency format, so they arrive as `$5,310.00`, not `RD$ 5.310,00`. Invoices (E31, E32, E44, E45, E46) use the phrase «el total de la factura original»; expenses (E43), purchases (E41) and foreign payments (E47) use «el total del documento original». The rule is the same; only the noun changes. No published rate limit in v1 The v1 API does not publish a formal req/s or req/min limit today, and does not expose `429` in a documented way. If your integration receives a code outside the table above, it most likely originates from the gateway or the protected network: retry with exponential backoff (250 ms, 500 ms, 1 s, 2 s) and open a ticket if it persists. ## Next steps Next step ## Continue here - [ Authentication How the X-Api-Key is issued and rotated. ](/en/desarrolladores/autenticacion) - [ Webhooks Events for reacting when the DGII rejects a document. ](/en/desarrolladores/webhooks) - [ e-CF lifecycle Why a 400 occurs before the DGII submission even travels. ](/en/desarrolladores/ciclo-ecf)