Idempotencia

Cómo repetir solicitudes sin ejecutarlas dos veces con el encabezado Idempotency-Key.

Las solicitudes POST, PATCH y DELETE aceptan el encabezado Idempotency-Key (1 a 255 caracteres; recomendamos un UUID v4 generado por solicitud). Reglas:

• Si repites la solicitud con la misma clave, el mismo método, la misma ruta y el mismo cuerpo dentro de las 24 horas siguientes, recibes la respuesta original (mismo estado y cuerpo) con el encabezado Idempotent-Replayed: true, sin que la operación se ejecute otra vez.
• Si la primera solicitud aún se está procesando, obtienes 409 idempotency_in_progress; espera un momento y reintenta con la misma clave.
• Si reutilizas la clave con otro método, otra ruta u otro cuerpo, obtienes 422 idempotency_key_reused.
• Solo se guardan las respuestas exitosas (2xx); los errores (4xx, 429, 5xx) no se guardan, de modo que puedes corregir y reintentar con la misma clave.

Usa siempre Idempotency-Key en acciones que disparan procesos (causar, enviar eventos DIAN) para que un reintento por timeout no las ejecute dos veces. Las cargas multipart/form-data (POST .../files) no participan de la idempotencia.