--- title: "Errores y códigos HTTP" description: "Envelope estándar { success, message } y la tabla de códigos HTTP que la API devuelve." canonical: https://factura.com.do/desarrolladores/errores lang: es generator: factura.com.do docs-index --- Convenciones # 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 | Código | Cuando ocurre | Acción esperada | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | 200 OK | GET con resultado o POST/PUT/DELETE procesado. Anular (void) y DELETE también responden 200 cuando fallan, con success: false | Lee success antes de dar la operación por hecha | | 400 Bad Request | JSON malformado, validación de cuerpo o regla de negocio incumplida | Lee message y corrige el body | | 401 Unauthorized | Falta o no es válida la X-Api-Key | Rotar la llave o renovarla | | 403 Forbidden | La llave es válida, pero el espacio de trabajo no tiene el plan Corporativo | Cambia al plan Corporativo | | 404 Not Found | id no existe en tu espacio de trabajo, o la nota referencia una secuencia que no existe | Verifica que el recurso pertenezca al tenant | | 500 Internal Server Error | Excepción no controlada, como crear un documento sin secuencia de NCF activa | Lee error; si es la secuencia, configúrala en la app. Si no, reintenta con backoff y abre un ticket si persiste | ## 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) 400-business-rule.json ``` { "success": false, "message": "El cliente está inactivo y no puede ser utilizado en documentos." } ``` ### No autorizado (401, sin cuerpo) 401-unauthorized.txt ``` HTTP/1.1 401 Unauthorized Content-Length: 0 ``` ### Conflicto de estado (400) 400-state-conflict.json ``` { "success": false, "message": "No se puede crear un Comprobante de Compras (E41) para un proveedor registrado en la DGII." } ``` ## Errores comunes | Caso | Código | Detalle | | ---------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------- | | Subdominio que no corresponde a ningún espacio de trabajo | 404 | Sin cuerpo | | X-Api-Key faltante o vencida | 401 | Sin cuerpo. Reintenta con la cabecera correcta | | Espacio de trabajo sin plan Corporativo | 403 | El acceso a la API REST está disponible solo en el plan Corporativo. | | No hay una secuencia de NCF activa para el tipo | 500 | No hay secuencia activa para el tipo de documento N | | Nota de crédito o débito con referenceSequence inexistente | 404 | No se encontró un documento con la secuencia 'E310000000001'. | | DELETE de un cliente que no existe | 200 | success: false · CustomerId with ID … not found. | | Anular un comprobante que la DGII está validando | 200 | success: false · Error al anular factura: No se puede anular una factura que está en proceso de validación por la DGII. … | | customerId u otro id no existe en el espacio de trabajo | 404 | Sin cuerpo (recurso no encontrado) | | Proveedor inactivo en el catálogo | 400 | El proveedor está inactivo y no puede ser utilizado en documentos. | | E41 con proveedor registrado en DGII | 400 | No se puede crear un Comprobante de Compras (E41) para un proveedor registrado en la DGII. | | Pagos no cuadran con el total del documento | 400 | La suma de los pagos (RD$ X) no coincide con el monto total del documento (RD$ Y). | | edit-amount con propuesta mayor al original | 400 | El monto propuesto (RD$ X) no puede exceder el total del documento original (RD$ Y). | | JSON malformado o tipo inesperado | 400 | Respuesta del binder de Minimal API; el shape exacto depende de la versión de ASP.NET Core. | Los mensajes parametrizados llegan con montos formateados Los detalles que muestran `RD$ X` y `RD$ Y` arriba son ilustrativos: el backend interpola las cifras reales con el formato de moneda de la cultura `en-US`, así que llegan como `$5,310.00` y no como `RD$ 5.310,00`. Las facturas (E31, E32, E44, E45, E46) usan la frase «el total de la factura original»; gastos (E43), compras (E41) y pagos al exterior (E47) usan «el total del documento original». La regla es la misma; solo cambia el sustantivo. Sin rate limit publicado en v1 La API v1 no publica hoy un límite formal de req/s ni req/min, y no expone `429` de forma documentada. Si tu integración recibe un código fuera de la tabla anterior, lo más probable es que provenga del gateway o de la red protegida: reintenta con backoff exponencial (250 ms, 500 ms, 1 s, 2 s) y abre ticket si persiste. ## Siguientes pasos Siguiente paso ## Continúa por aquí - [ Autenticación Cómo se emite y rota la X-Api-Key. ](/desarrolladores/autenticacion) - [ Webhooks Eventos para reaccionar cuando la DGII rechaza un comprobante. ](/desarrolladores/webhooks) - [ Ciclo del e-CF Por qué un 400 ocurre antes que el envío DGII llegue a viajar. ](/desarrolladores/ciclo-ecf)