Express.js
Explica cómo diseñar operaciones reintentables con claves de idempotencia, persistencia del resultado, scope, expiración y coordinación con transacciones.
Idempotencia permite repetir una misma intención sin duplicar su efecto de negocio. Es una propiedad del contrato completo, no únicamente del método HTTP.
Las redes fallan de forma ambigua: el cliente puede enviar una creación, el servidor confirmarla y la respuesta perderse. El cliente no sabe si debe repetir.
request enviada
↓
operación confirmada
↓
response perdida
↓
retry del clienteSin idempotencia, el retry puede crear dos órdenes, cobrar dos veces o registrar dos movimientos.
GET, PUT y DELETE se consideran idempotentes por intención. POST no lo es automáticamente, aunque puede diseñarse como idempotente mediante una key.
Idempotente no significa que todas las respuestas sean iguales. Un DELETE puede devolver 204 y después 404, mientras el estado final sigue siendo “recurso ausente”.
POST /orders
Idempotency-Key: 7f632...El servidor asocia la key con:
recibir key
↓
calcular fingerprint
↓
insertar registro único
↓
ejecutar operación y persistir resultado
↓
guardar response
↓
repeticiones devuelven el mismo resultadoCREATE TABLE idempotency_keys (
tenant_id uuid NOT NULL,
key text NOT NULL,
request_hash text NOT NULL,
status text NOT NULL,
response_status integer,
response_body jsonb,
created_at timestamptz NOT NULL DEFAULT now(),
expires_at timestamptz NOT NULL,
PRIMARY KEY (tenant_id, key)
);La constraint resuelve carreras entre instancias. No uses memoria local.
Debe rechazarse con conflicto. Reutilizar una key para otra intención es un error del cliente.
key igual + hash igual
→ devolver resultado almacenado
key igual + hash diferente
→ 409 conflictDos requests simultáneas pueden encontrar la key mientras la primera trabaja. Opciones:
La política debe estar documentada.
Idealmente, la reserva de key y el cambio de negocio se coordinan en la misma transacción. Si el efecto ocurre en un proveedor externo, necesitas una máquina de estados y reconciliación.
No mantengas una transacción PostgreSQL abierta durante una llamada de red larga sin evaluar locks y pool.
Crear una orden:
processing.Crear la misma fila una vez no basta si también envías email o publicas eventos. Usa outbox o efectos con identificadores deduplicables.
order + outbox event + idempotency result
→ misma transacciónLas keys no se conservan eternamente. El TTL debe superar la ventana realista de retries. Tras expirar, repetir podría crear un nuevo efecto; el contrato debe comunicarlo.
Estos casos requieren reconciliación, scope correcto y políticas explícitas.
Idempotencia no reemplaza:
Prueba la misma key de forma secuencial y concurrente; payload distinto; caída entre etapas; expiración; aislamiento por tenant; efectos secundarios únicos.
Paginación, filtros y ordenamiento diseña colecciones predecibles y limitadas.