Saltar al contenido principal

Errores y reintentos

La regla principal es sencilla: si no sabes si una emision fue recibida, reenvia el mismo JSON con el mismo eNCF.

Formato de error​

{
  "ok": false,
  "error": {
    "code": "ENCF_REQUIRED",
    "message": "El eNCF asignado por el POS es requerido para emitir el documento",
    "details": { "field": "ECF.Encabezado.IdDoc.eNCF" }
  },
  "correlationId": "c0ffee00-1234-..."
}

Guarda correlationId junto al identificador de tu operacion. Soporte lo utilizara para localizar la solicitud sin pedirte datos fiscales sensibles.

Matriz de decision​

ResultadoAccion de tu integracion
400 o 422Corrige el payload. No reintentes el mismo contenido automaticamente.
401Deten el envio y corrige la API key del ambiente.
403Deten el envio y asigna el scope requerido.
404Verifica ambiente, ruta e identificador.
409Lee error.code; no cambies automaticamente eNCF, decision o payload.
429Respeta Retry-After y aplica backoff con jitter.
500, 502, 503, 504En emision, reintenta el mismo JSON con el mismo eNCF.
Timeout o conexion cerradaTrata el resultado como incierto y repite el mismo JSON con el mismo eNCF.

Politica recomendada​

  1. Timeout HTTP de acuerdo con la latencia de tu red; no dejes conexiones sin limite.
  2. Backoff exponencial con jitter, por ejemplo 1 s, 2 s, 4 s, 8 s y 16 s.
  3. Respeta Retry-After cuando exista.
  4. Limita intentos y mueve la operacion a una cola de revision sin cambiar el eNCF ni el JSON.
  5. Despues de recibir documentId o encf, consulta status/batch; no vuelvas a emitir para consultar progreso.

Conflictos por eNCF​

  • ENCF_PAYLOAD_MISMATCH: el eNCF ya fue usado con informacion fiscal diferente. Investiga y concilia; no sobrescribas la operacion original.
  • ENCF_REPLAY_UNVERIFIABLE: existe un registro historico de ese eNCF cuya huella no puede compararse. Consulta el estado o contacta soporte con el correlationId.
  • ENCF_ANNULLED: el eNCF pertenece a un rango anulado y no puede emitirse.
Rechazo DGII no es error de transporte

Un documento rejected ya alcanzo un estado fiscal final. No reenvies el mismo eNCF. Corrige la causa y sigue el procedimiento fiscal correspondiente para emitir un nuevo comprobante.