Ir al contenido

Errores

Hay dos clases de error:

  1. Errores de la solicitud: la API responde 4xx y no se emite nada (no se consume e-NCF ni se cobra en tu plan).
  2. Rechazos de la DGII: el comprobante se emitió y la DGII lo rechazó. Llegan como estado Rejected, con los mensajes de la DGII.

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.

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
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.

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. …"
}
]
}
  • code y value son 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».
  • sequenceConsumed dice si la DGII consumió el e-NCF: si es false, la corrección puede usar el mismo número.

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.