Errores
Hay dos clases de error:
- Errores de la solicitud: la API responde
4xxy no se emite nada (no se consume e-NCF ni se cobra en tu plan). - Rechazos de la DGII: el comprobante se emitió y la DGII lo rechazó. Llegan como estado
Rejected, con los mensajes de la DGII.
Formato
Sección titulada «Formato»Los errores usan el formato estándar Problem Details (application/problem+json), con un code estable que puedes
usar en tu código:
{ "title": "El e-NCF E310000600002 ya fue utilizado; no se emitió el comprobante. …", "status": 409, "code": "invoice.encf_taken", "errors": [ { "code": "invoice.encf_taken", "field": "Encabezado.IdDoc.eNCF", "message": "El e-NCF E310000600002 ya fue utilizado; …" } ]}errors trae el detalle por campo cuando aplica. El texto puede cambiar; el code, no.
Códigos HTTP
Sección titulada «Códigos HTTP»| HTTP | Significa | ¿Reintentar? |
|---|---|---|
400 |
Solicitud mal formada (falta un header, un parámetro inválido) | No: corregir |
401 |
Sin API key, o la key no es válida | No: revisar la key |
403 |
La key no puede hacer eso (otra empresa, límite del plan) | No |
404 |
No existe, o no es de tu cuenta | No |
409 |
Conflicto con el estado actual | Según el código |
413 |
Archivo demasiado grande | No |
422 |
El comprobante tiene errores | No: corregir el documento |
429 |
Demasiadas solicitudes | Sí, después de Retry-After |
5xx |
Error nuestro o momentáneo | Sí, con la misma Idempotency-Key |
Códigos más comunes
Sección titulada «Códigos más comunes»code |
HTTP | Qué significa | Qué hacer |
|---|---|---|---|
idempotency.key_required |
400 | Falta el header Idempotency-Key |
Enviarlo (uno nuevo por factura). |
idempotency.key_reused |
409 | Esa clave ya se usó con otra factura | Usar una clave nueva para la factura nueva. |
wait.invalid |
400 | ?wait con un valor no admitido |
Usar result, sent o signed. |
company.required |
422 | La key es para todas las empresas y falta companyId |
Enviar companyId, o usar una key restringida. |
company.not_in_key |
403 | companyId es de otra empresa que la de la key |
Omitir companyId o enviar el de la key. |
company.not_found |
404 | La empresa no existe en tu cuenta | Revisar el ID. |
company.inactive |
409 | La empresa está desactivada | Activarla en el portal. |
company.certificate_missing |
409 | La empresa no tiene un certificado vigente | Cargar el certificado en el portal. |
ecf.validation_failed |
422 | El documento no cumple las reglas de la DGII | Ver errors: campo y motivo. |
ecf.rnc_emisor_mismatch |
422 | rncEmisor no es el de la empresa |
Corregir el RNC. |
sequence.unavailable |
409 | No hay una secuencia vigente con números para ese tipo | Registrar una secuencia en el portal. |
sequence.expiry_required |
422 | e-NCF propio sin secuencia registrada y sin fechaVencimientoSecuencia |
Enviar la fecha de vencimiento. |
sequence.expired |
422 | La secuencia venció | Usar una secuencia vigente. |
encf.invalid |
422 | El e-NCF no tiene el formato | Corregir el formato (E + tipo + 10 dígitos). |
encf.type_mismatch |
422 | El tipo del e-NCF no es el del e-CF | Corregir el e-NCF o el tipo. |
encf.outside_client_range |
422 | El e-NCF propio está en el tramo del servicio | Usar un número del tramo de tu sistema. |
invoice.encf_taken |
409 | Ese e-NCF ya se usó | Tu sistema decide el siguiente número. Nunca lo cambiamos. |
encf.consumed |
422 | Corrección con un e-NCF que la DGII ya consumió | Enviar la corrección con otro e-NCF. |
invoice.not_found |
404 | El comprobante no existe en tu cuenta | Revisar el ID. |
invoice.not_resendable |
409 | Solo se reenvían Failed o Rejected |
Revisar el estado. |
xml.xsd |
422 | El XML firmado no cumple el esquema | Ver errors. |
signature.invalid |
422 | La firma del XML no es válida (o el XML se modificó después de firmar) | Firmar de nuevo. |
rfce.required |
422 | Tipo 32 menor sin el RFCE firmado | Enviar el campo rfce. |
plan.limit_reached |
403 | Llegaste al límite de comprobantes del plan | Escribir a soporte: soporte@ecfhub.com.do. |
rate_limit.exceeded |
429 | Demasiadas solicitudes por minuto | Esperar Retry-After. |
Mensajes de la DGII
Sección titulada «Mensajes de la DGII»Cuando la DGII rechaza un comprobante (o lo acepta con condiciones), sus mensajes vienen en dgii.messages:
"dgii": { "code": 2, "status": "Rechazado", "sequenceConsumed": false, "messages": [ { "code": "135", "value": "Secuencia no autorizada …", "hint": "El e-NCF no está en un rango que la DGII haya autorizado a la empresa para ese tipo en este ambiente. …" } ]}codeyvalueson los de la DGII, sin cambios.hint(cuando lo hay) explica qué significa y qué hacer, en lenguaje claro. Es lo mismo que el portal muestra como «Qué significa».sequenceConsumeddice si la DGII consumió el e-NCF: si esfalse, la corrección puede usar el mismo número.
¿Necesitas ayuda?
Sección titulada «¿Necesitas ayuda?»Si un error no se explica aquí o un comprobante no avanza, escribe a
soporte@ecfhub.com.do con el code del error, el id del comprobante (o su e-NCF) y la
hora. Nunca envíes tu API key ni tu certificado.