Errores, idempotencia y reintentos

Formato Problem

Todos los errores usan el mismo cuerpo:

{
  "code": "FISCAL_VALIDATION_FAILED",
  "message": "…",
  "request_id": "…",
  "retryable": false,
  "action": "fix_request",
  "errors": [{ "…": "errores por campo" }]
}

• action: fix_request, check_credentials, check_permissions, consult_operation, retry_same_key, top_up, contact_support o none.
• Puede incluir operation_id, resource_id y resource_type.
• Guarda el cuerpo de forma privada junto con request_id. No registres la clave ni material de firma.

Qué hacer con cada respuesta

Lo que responde la DIAN

Que Cufy acepte tu factura (202) no significa que la DIAN la haya validado. Eso pasa después, y llega en dian.status cuando consultas el documento o en el webhook document.validated.

Cuando hay algo que leer, viene en dian.errors y dian.warnings, con mensajes que empiezan por Regla: CÓDIGO,. Un error rechaza el documento; un aviso no: la factura vale igual.

Reglas que vas a ver en el sandbox

Estas son las que aparecen a diario. Varias no son culpa tuya: el sandbox emite con un emisor de pruebas compartido, y la DIAN comenta ese emisor en cada documento.

Cualquier otra regla llega con las palabras de la DIAN tal cual. Son mensajes escritos para contadores, no para desarrolladores: si uno no se entiende, escríbenos con el request_id y el código de la regla.

Cuando el documento se queda a medio camino

Si el documento no llegó a la DIAN, su estado trae un blocked_reason:

Reanudar no emite un documento nuevo: conserva su número y su identidad. Ver Corregir y reanudar.

Idempotencia

Toda mutación exige Idempotency-Key: de 8 a 128 caracteres, A-Z a-z 0-9 . _ : -, empezando por letra o dígito.

• La clave vale dentro de empresa, ambiente, operación y recurso destino. Se retiene al menos 90 días y mientras haya trabajo pendiente.
• Misma clave y mismo contenido → devuelve el resultado original (202 con el mismo document_id).
• Misma clave y contenido distinto → 409 IDEMPOTENCY_CONFLICT.
• Misma referencia externa y contenido distinto → 409 EXTERNAL_REFERENCE_CONFLICT.
• Los decimales se comparan como texto: "1.0" y "1.00" son contenidos distintos.
• No dependas del encabezado Idempotency-Replayed (el servicio no lo emite). Compara el ID devuelto y consulta el recurso.

Reintentar sin duplicar

Serializa el cuerpo una sola vez y guarda esos bytes, no el objeto que los produjo: volver a serializar puede cambiar el orden de las claves o los decimales, y entonces la misma clave de idempotencia devuelve 409 en lugar de tu documento.

Un documento con dian.status: unknown exige conciliación. No es un rechazo y no autoriza otra emisión.

Recursos versionados

Los recursos que lo implementan devuelven ETag. Las acciones que exigen If-Match rechazan versiones antiguas con 409 VERSION_CONFLICT. Vuelve a consultar y evalúa la acción con la versión actual.

Límites de tasa

La API aplica límites antes de leer el cuerpo o autenticar, y otros después de identificar empresa y clave. También cuentan las consultas, las credenciales inválidas y las rutas inexistentes. Son independientes del saldo.

Los límites se aplican en varios niveles a la vez: por dirección IP, por empresa y ambiente, por clave y, aparte, a las escrituras. Una cuenta del sandbox tope con el suyo mucho antes que con los demás; los valores que te afectan están en Límites del sandbox.

Dos cosas que sorprenden: varias claves de la misma empresa comparten su límite, y varios clientes detrás de la misma IP también. Que una clave esté ociosa no te da margen extra.

Un rechazo devuelve HTTP_RATE_LIMIT o HTTP_CONCURRENCY_LIMIT (429 para límites de cliente, 503 por saturación) o HTTP_STATE_CAPACITY (503), con retryable: true, action: retry_same_key y Retry-After en segundos.

• Espera al menos Retry-After y añade variación aleatoria.
• Repite con la misma clave y el mismo cuerpo.
• Una solicitud rechazada por estos límites no reserva numeración ni consume crédito.

Límites del sandbox

Una cuenta del sandbox público es gratuita y emite con el emisor compartido de habilitación, así que además de lo anterior tiene tres límites propios:

Ninguna factura rechazada por un límite consume numeración: reintenta con la misma Idempotency-Key cuando pase la espera. El correo del sandbox solo llega a la dirección de la persona dueña de la cuenta; para probar notificaciones a tu sistema, usa webhooks. Una empresa real no tiene estos límites.