IDEMPOTENCIA: EL PILAR OCULTO DE LAS APIs CONFIABLES

El problema que la idempotencia resuelve

Imagina que un cliente hace clic en 'Pagar'. La solicitud sale hacia tu servidor, el servidor procesa el pago, y justo cuando va a responder, la conexión se cae. El cliente nunca recibe confirmación. ¿Qué hace? Reintenta. Pero, ¿se procesó el pago la primera vez o no?

Este escenario no es una rareza teórica, es el día a día de cualquier sistema distribuido. Las solicitudes se pierden, los timeouts ocurren, los clientes reintentan automáticamente, las colas de mensajes redistribuyen mensajes que creen perdidos. En todos estos casos, el mismo request puede llegar a tu sistema más de una vez. Si tu operación no es idempotente, cada una de esas repeticiones genera un efecto adicional: otro cargo, otro email, otro registro.

Las redes no son confiables. Los reintentos son inevitables. La idempotencia es lo único que está entre esa realidad y un desastre en producción.

La definición correcta

Una operación es idempotente si ejecutarla múltiples veces produce exactamente el mismo efecto que ejecutarla una sola vez. No es que devuelva la misma respuesta es que el estado del sistema después de n ejecuciones es indistinguible del estado después de una sola ejecución.

Esta distinción importa. Un endpoint puede devolver la misma respuesta en cada llamada y, sin embargo, no ser idempotente si cada llamada modifica algo internamente por ejemplo, incrementando un contador en cada intento aunque la respuesta visible al cliente sea idéntica.

Idempotencia natural vs idempotencia diseñada

Algunas operaciones son idempotentes por naturaleza, sin que nadie tenga que diseñarlas así. Un GET que consulta datos es idempotente porque leer no cambia nada. Un PUT que establece un valor específico 'el nombre de este usuario es Juan' es idempotente porque repetirlo deja el mismo nombre, sin importar cuántas veces se ejecute.

El problema aparece con los POST. Un POST que crea un nuevo recurso 'crea un pedido' no es idempotente por defecto: cada llamada crea un pedido nuevo. Aquí es donde la idempotencia deja de ser gratuita y empieza a requerir diseño deliberado.
 

Cómo se implementa en la práctica

El patrón más extendido en APIs modernas es la idempotency key: el cliente genera un identificador único, normalmente un UUID, y lo envía como cabecera en la solicitud. El servidor recuerda qué claves ya procesó. Si llega una solicitud con una clave ya vista, el servidor no repite la operación: simplemente devuelve el resultado que ya guardó la primera vez.

Stripe, uno de los procesadores de pago más usados del mundo, popularizó este patrón con su cabecera Idempotency-Key. Si tu aplicación reintenta una solicitud de cobro con la misma clave, Stripe garantiza que el cargo solo se procesa una vez, sin importar cuántas veces llegue la solicitud.

Las piezas necesarias

• Una clave única generada por el cliente, no por el servidor porque si el servidor la genera después de fallar, el cliente no la conocerá para reenviarla.

• Un almacén donde guardar qué claves ya se procesaron y con qué resultado normalmente con un tiempo de expiración razonable, no para siempre.

• Una ventana de tiempo de bloqueo mientras la operación original todavía se está procesando, para evitar que dos solicitudes con la misma clave se ejecuten en paralelo y generen una condición de carrera.

• Una estrategia clara para diferenciar 'esta clave ya terminó con éxito' de 'esta clave está en proceso' de 'esta clave falló y se puede reintentar de verdad'.

Dónde más allá de las APIs importa esto

La idempotencia no es exclusiva de endpoints HTTP. En colas de mensajes como Kafka, RabbitMQ o SQS, la mayoría de sistemas garantizan 'at-least-once delivery' el mensaje llegará al menos una vez, pero podría llegar más de una. Esto significa que cada consumer que procesa mensajes de una cola debe asumir que puede recibir el mismo mensaje dos veces, y su lógica de procesamiento tiene que ser idempotente para no duplicar efectos.

En sistemas de Event Sourcing, donde los proyectores escuchan eventos para actualizar vistas de lectura, la idempotencia es igual de crítica: si el mismo evento se procesa dos veces por un reintento o reprocesamiento, la proyección no debería duplicar el cambio.

En integraciones entre microservicios, cuando un servicio llama a otro y no recibe respuesta a tiempo, reintentar sin idempotencia puede provocar efectos en cascada: un servicio de inventario que descuenta stock dos veces porque el servicio de pedidos reintentó tras un timeout que en realidad sí se había completado.

El error más común

Asumir que un timeout significa que la operación no se ejecutó. Un timeout solo significa que no recibiste la respuesta a tiempo la operación pudo completarse perfectamente en el servidor. Reintentar sin idempotencia, asumiendo que 'no pasó nada', es la causa más frecuente de duplicados en producción.

Lo que no es idempotencia

Vale la pena aclarar tres confusiones frecuentes. Idempotencia no es lo mismo que seguridad (safety) en el sentido de los métodos HTTP, un método 'seguro' como GET no modifica el servidor, mientras que un método idempotente como PUT sí puede modificarlo, simplemente de forma repetible.

Idempotencia tampoco es lo mismo que atomicidad. Una operación puede ser atómica, se ejecuta completa o no se ejecuta en absoluto, sin ser idempotente, y viceversa. Son propiedades independientes que conviene no mezclar al diseñar sistemas confiables.

Y, quizás lo más importante: idempotencia no es lo mismo que deduplicación automática de la infraestructura. Algunas colas de mensajes ofrecen deduplicación con cierta ventana de tiempo, pero eso no exime a tu lógica de aplicación de ser idempotente esa garantía de infraestructura cubre un escenario limitado, no todos los caminos por los que un duplicado puede llegar a tu sistema.

CONCLUSIÓN

La idempotencia no es una optimización elegante ni un detalle de buenas prácticas que se puede posponer. Es una propiedad estructural que determina si tu sistema sobrevive a la realidad de las redes distribuidas o si, tarde o temprano, cobra dos veces a un cliente, envía un correo duplicado, o crea pedidos fantasma.

La próxima vez que diseñes un endpoint, un consumer de mensajes o una integración entre servicios, no te preguntes solo 'qué pasa si esto funciona'. Pregúntate 'qué pasa si esto se ejecuta dos veces sin que nadie se dé cuenta', porque eventualmente, ocurrirá.