Idempotencia
El header x-idempotency evita que una operación se procese dos veces cuando hay reintentos de
red. Es obligatorio en toda request y forma parte del canonical string firmado.
Reglas
- Longitud mínima de 5 caracteres. Una clave más corta se rechaza con
400. - La clave es parte de los headers firmados, así que cambiarla cambia la firma.
- El servidor deduplica por clave: si reenviás la misma clave de idempotencia para la misma operación, no se reprocesa; recibís el resultado de la operación original.
Cómo generar la clave
Cada operación lógica distinta debe tener una clave única. La recomendación es generar un identificador único por operación (por ejemplo un UUID v4, o un identificador propio de la operación en tu sistema) y reutilizarlo solo si necesitás reintentar esa misma operación.
El script de Postman, si no encontrás una idempotency_key definida, usa Date.now() como valor
por defecto para facilitar las pruebas. Eso no es adecuado para producción: cada reintento
generaría una clave distinta y la operación podría procesarse más de una vez. En producción
generá una clave única y estable por operación, y reusala en los reintentos.
Conflictos
Si reusás una clave de idempotencia que ya corresponde a otra operación, la API responde 500
con { "success": false, "error": "Operation with idempotency key \"...\" already exists" }. Ver
Códigos de error.
Ejemplo (Postman)
Para fijar una clave estable en Postman en vez de la autogenerada, definí la variable
idempotency_key antes de enviar:
pm.environment.set("idempotency_key", "transfer-2026-07-24-0001");