Idempotencia

Toda operación de escritura exige la cabecera Idempotency-Key:

curl -X POST https://api-test.facto.lat/v1/facturas \
  -H "x-api-key: $LLAVE" \
  -H "Idempotency-Key: 5f0c7e0a-4b1e-4c9a-9d2e-8f3a1b6c9d0e" \
  ...

El problema que resuelve

Mandas una factura y la red se corta antes de que llegue la respuesta. ¿Se emitió o no? Sin idempotencia, reintentar puede duplicar la factura — con numeración del SRI consumida y todo. Con idempotencia, reintentar es siempre seguro: si la primera llegó, el reintento devuelve la misma respuesta original, marcada con la cabecera idempotent-replay: true; si no llegó, se procesa como nueva.

La regla práctica para tu cliente HTTP:

Timeout o error de red → reintenta con la misma clave. Contenido nuevo → clave nueva.

Cómo generarla

Un identificador único por intento, de hasta 255 caracteres. Un UUID va perfecto. Si tu sistema tiene un identificador natural de la operación (el ID de la venta en tu base), úsalo: así el reintento sale gratis desde cualquier proceso.

Los tres errores posibles

Situación	HTTP	Código	Qué hacer
No mandaste la cabecera	400	FACTO-2012	Agregarla: un UUID por intento.
Misma clave, contenido distinto	422	FACTO-2010	Contenido nuevo, clave nueva.
La primera petición sigue en curso	409	FACTO-2011	Esperar Retry-After y repetir la misma petición.

El FACTO-2010 es una protección, no una molestia: significa que estuviste a punto de sobreescribir un intento con datos distintos bajo la misma clave — un bug en tu generación de claves que conviene encontrar en pruebas.