Errores y reintentos

No todos los errores se recuperan repitiendo una solicitud. Clasifica primero.

Matriz de decisión

Clase	Ejemplo	Acción
Autenticación	Credencial inválida, expirada o revocada	Detener, rotar o corregir la credencial.
Autorización	Scope o integración no disponible en el ambiente	Corregir configuración; no reintentar en bucle.
Validación	Campo requerido, total incoherente, regla fiscal	Corregir datos con intervención del sistema origen.
Conflicto	Idempotencia o external_id ya utilizado	Consultar el recurso existente y comparar intención.
Límite	Demasiadas solicitudes	Respetar Retry-After y aplicar backoff.
Transitorio	Red, timeout previo a envío confirmado, 5xx	Reintentar de forma acotada con la misma identidad.
Resultado incierto	Timeout después de una posible presentación	Reconciliar; no crear otra emisión.

Códigos públicos de v1

Código	Qué hacer
bad_request, invalid_json	Corrige el request HTTP o el JSON.
validation_error	Corrige los campos indicados; no reintentes el mismo cuerpo.
unauthorized	Proporciona una credencial válida.
forbidden	Corrige scopes o disponibilidad de la integración en el ambiente.
not_found	Verifica el identificador y el contribuyente dentro del alcance autorizado.
idempotency_mismatch, external_id_conflict	Recupera la intención existente y compara el cuerpo.
operational_readiness_failed	Fuera de sandbox, completa identidad pública, numeración, certificado, secuencia o preparación requerida.
artifact_not_ready	Espera el estado aplicable; en sandbox el artefacto fiscal no existe.
rate_limited	Respeta Retry-After y reduce la tasa.
service_unavailable, internal_error	Conserva identidad y request_id; reintenta de forma acotada.

OpenAPI define qué códigos puede devolver cada operación y su estado HTTP. Un código estable es apto para automatización; el texto humano puede mejorar sin cambiar el contrato.

Estructura de error

El contrato define códigos estables, detalles y request_id. No automatices decisiones usando el texto humano del mensaje.

Registra:

• estado HTTP;
• code;
• request_id;
• campos o detalles permitidos;
• intento y hora;
• external_id.

No registres claves, certificados, contraseñas ni XML completos.

Política de reintento

Para fallos transitorios:

1. conserva la misma intención e idempotencia;
2. aplica backoff exponencial con jitter;
3. limita intentos y duración total;
4. respeta Retry-After;
5. abre un circuito ante una degradación sostenida;
6. envía a reconciliación cuando no puedes determinar el resultado.

Un rechazo fiscal no es un 5xx

La DGII puede responder técnicamente y rechazar el documento por reglas fiscales. Ese resultado necesita corrección o una acción fiscal; repetir los mismos datos no ayuda.

Cuándo solicitar soporte

Incluye:

• ambiente;
• contribuyente o RNC, si el canal es seguro;
• external_id;
• identificador CierreListo;
• request_id;
• fecha y zona horaria;
• código de error.

Nunca envíes la API key o contraseña del certificado.

Configurar webhooks →