¿Qué es la idempotencia, y cómo hacen las idempotency keys que los retries sean seguros?

Question

IT Interview Practice · Accepted Answer

La **idempotencia** significa que realizar una operación **varias veces tiene el mismo efecto que realizarla una vez**. Importa porque las redes no son fiables: cuando un client envía un request y la response nunca llega, no puede saber si el server lo procesó. Si reintenta, una operación no idempotente podría ejecutarse dos veces.

## El problema

```text
Client ──POST /payments {$100}──▶ Server   (charges $100 ✓)
Client ◀────────X (timeout)────── Server   (response lost)
Client ──POST /payments {$100}──▶ Server   (charges $100 AGAIN ✗ → $200!)
```

`GET`, `PUT` y `DELETE` son idempotentes por naturaleza, así que reintentarlos es seguro. `POST` **no** lo es — de aquí es exactamente de donde salen los cargos duplicados y los orders duplicados.

## La solución: idempotency keys

El client genera una **key única** (normalmente un UUID) para la operación lógica y la envía en una cabecera. El server almacena la key junto con el resultado; si la misma key llega de nuevo, devuelve el resultado **almacenado** en lugar de volver a ejecutar.

```http
POST /payments HTTP/1.1
Idempotency-Key: 5f2b8c1e-3a4d-4e6f-9c0b-1a2b3c4d5e6f
Content-Type: application/json

{ "amount": 100, "currency": "usd" }
```

```text
Server logic on receiving a request with an Idempotency-Key:
  1. Look up the key in a store (e.g. Redis/DB).
  2. If found → return the saved response (no re-charge).      ← the retry case
  3. If not  → process, save (key → response), then return.
  (Wrap 3 in a transaction / lock so concurrent retries don't double-execute.)
```

La **misma key** en el retry produce el mismo `200` y el mismo payment — al cliente se le cobra una vez. Así es exactamente como funciona la API de Stripe.

## Por qué es importante

Esta pregunta separa a los ingenieros que diseñan para el happy path de los que diseñan para el **fallo**, que es de lo que trata la fiabilidad en producción. Los sistemas distribuidos garantizan que los timeouts y los fallos parciales *ocurrirán*, así que cualquier endpoint con side effects — pagos, orders, enviar dinero — necesita una estrategia de retry, y "simplemente reintenta" es peligroso para `POST`. El entrevistador quiere oír la idea en dos partes: primero, que la idempotencia es una propiedad que puedes *diseñar de antemano* (haciendo `PUT`/`DELETE` seguros por naturaleza, y dando a `POST` una **idempotency key** cuando no lo es); y segundo, el detalle sutil de concurrencia — dos retries que llegan a la vez no deben ejecutarse ambos, así que la comprobación de la key y la escritura necesitan un lock o una unique constraint. Hacer bien esto es la diferencia entre cobrar a un cliente una vez y cobrarle dos, por lo que toda API seria de pagos y comercio lo implementa.

El problema

La solución: idempotency keys

Por qué es importante

Preguntas relacionadas