Idempotencia en APIs distribuidas: más allá del retry
8 min de lectura
El problema
En cuanto una llamada atraviesa la red, el cliente ya no puede saber si el efecto ocurrió: un timeout es indistinguible de un éxito lento. La única respuesta robusta es reintentar, y reintentar exige idempotencia.
Claves de idempotencia
POST /api/v1/payments
Idempotency-Key: 7f9c2ba4-e88f-11ed-a05b-0242ac120003
El servidor persiste la clave junto con el resultado de la primera ejecución y responde el mismo resultado ante repeticiones. Tres detalles que suelen olvidarse:
- La clave debe guardarse en la misma transacción que el efecto.
- Necesita TTL y estrategia de limpieza.
- Una repetición con el mismo key pero distinto payload es un
409.
Outbox pattern
Para efectos que cruzan servicios (publicar un evento tras confirmar un pago), el patrón outbox garantiza atomicidad: se escribe el evento en una tabla local dentro de la transacción y un relay lo publica después. El consumidor, a su vez, deduplica por event_id.
Conclusión
La idempotencia no es una feature: es la condición de posibilidad de los reintentos, y los reintentos son la condición de posibilidad de operar sistemas distribuidos con calma.