¿Qué hace que un endpoint sea idempotente, y cómo funcionan las claves de idempotencia en operaciones no idempotentes como los pagos?

#Idempotente, seguro, y por qué la diferencia importa

Una operación es idempotente si ejecutarla una vez produce el mismo resultado en el servidor que ejecutarla dos, diez o mil veces con la misma entrada. No dice nada sobre si la primera llamada tiene un efecto secundario — DELETE /users/42 sin dudas cambia el estado la primera vez — solo promete que repetir exactamente la misma petición después no acumula ese efecto. Es una garantía más angosta que segura (sin efectos secundarios en absoluto, como GET), y es fácil confundir ambos conceptos. PUT /users/42 con una representación completa es idempotente (reemplazar un recurso con el mismo valor dos veces deja todo igual que reemplazarlo una sola vez) pero no es seguro (sí escribe).

#Dónde se rompe esto en el mundo real

HTTP te da la garantía de idempotencia de PUT y DELETE gratis — el servidor es responsable de implementarlos así, y si lo hace, un cliente puede reintentar a ciegas después de un timeout sin ningún riesgo. El problema es que la operación más propensa a reintentos en un backend típico — "crear algo" — es un POST, y POST no trae esa garantía. En ningún lado esto es más peligroso que en pagos: un cliente manda POST /payments, la tarjeta se cobra, y la respuesta se pierde por un corte de red antes de llegar al cliente. Desde el punto de vista del cliente, la petición pudo haber fallado. El único instinto seguro — reintentar — ahora arriesga cobrarle dos veces al cliente por la misma compra.

#Claves de idempotencia: haciendo que POST se comporte

Una clave de idempotencia es un token único generado por el cliente — típicamente un UUID — que se envía como header (Idempotency-Key) junto a una petición que naturalmente no es idempotente. El contrato del servidor pasa a ser: "la primera vez que vea esta clave, voy a ejecutar la operación de verdad y guardar el resultado; cada petición posterior con la misma clave recibe ese mismo resultado guardado, sin tocar el mundo de nuevo." El cliente es responsable de reutilizar exactamente la misma clave en los reintentos de la misma operación lógica, y de generar una clave nueva para una operación genuinamente distinta.

Del lado del servidor hacen falta tres cosas para hacerlo bien:

1. Reserva atómica. Dos peticiones con la misma clave pueden llegar en simultáneo (un cliente que hace timeout y reintenta de inmediato, compitiendo con su propia petición original). El servidor debe reclamar la clave atómicamente antes de hacer cualquier trabajo — un INSERT ... ON CONFLICT DO NOTHING en Postgres?, o un SET key value NX en Redis — para que exactamente un llamador avance y al otro se le diga que espere o se le devuelva el resultado eventual.
2. Huella digital del payload. Guardar un hash del cuerpo de la petición junto con la clave. Si la misma clave llega con un cuerpo distinto, eso es un bug del cliente (o un actor malicioso), no un reintento legítimo — hay que rechazarlo en vez de devolver silenciosamente un resultado viejo para la petición equivocada.
3. Un cache de respuesta con un TTL razonable. Guardar el código de estado y el cuerpo de la operación completada para que los reintentos puedan repetirlo tal cual, y hacerlo expirar en una ventana acotada (24 a 72 horas es típico) en vez de para siempre, porque las claves de idempotencia están pensadas para cubrir la ventana de reintento del cliente, no para convertirse en un libro contable permanente.

Ajustar líneas largas
import json
import hashlib
import redis
from flask import Flask, request, jsonify

app = Flask(__name__)
r = redis.Redis(host="localhost", port=6379, db=0)

IDEMPOTENCY_TTL_SECONDS = 24 * 60 * 60


def idempotent(view_func):
    def wrapper(*args, **kwargs):
        key = request.headers.get("Idempotency-Key")
        if not key:
            return jsonify({"error": "Idempotency-Key header is required"}), 400

        body_hash = hashlib.sha256(request.get_data()).hexdigest()
        store_key = f"idem:{key}"

        reserved = r.set(
            store_key,
            json.dumps({"status": "in_progress", "body_hash": body_hash}),
            nx=True,
            ex=IDEMPOTENCY_TTL_SECONDS,
        )

        if not reserved:
            existing = json.loads(r.get(store_key))
            if existing.get("body_hash") != body_hash:
                return jsonify({"error": "Idempotency-Key reused with a different body"}), 422
            if existing.get("status") == "in_progress":
                return jsonify({"error": "Original request is still processing"}), 409
            return jsonify(existing["response_body"]), existing["status_code"]

        try:
            status_code, response_body = view_func(*args, **kwargs)
        except Exception:
            r.delete(store_key)
            raise

        r.set(
            store_key,
            json.dumps({
                "status": "completed",
                "body_hash": body_hash,
                "status_code": status_code,
                "response_body": response_body,
            }),
            ex=IDEMPOTENCY_TTL_SECONDS,
        )
        return jsonify(response_body), status_code

    wrapper.__name__ = view_func.__name__
    return wrapper


@app.route("/payments", methods=["POST"])
@idempotent
def create_payment():
    data = request.get_json()
    payment = charge_card(data["card_token"], data["amount_cents"])
    return 201, {"id": payment.id, "status": payment.status}

Un cliente que llama a este endpoint manda la clave él mismo:

POST /payments HTTP/1.1
Host: api.example.com
Idempotency-Key: 6c1f1c9e-df7a-4b1a-9e2b-6a2b6a9b6e10
Content-Type: application/json

{ "card_token": "tok_abc123", "amount_cents": 4999 }

🧠 Check your understanding
0/3 · 0/3 answered
1. ¿Qué par de métodos HTTP son idempotentes pero NO seguros?
PUT y DELETEOPTIONS y TRACEGET y HEADPOST y PATCH
2. La petición POST /payments de un cliente hace timeout pero el cobro sí se procesó en el servidor. El cliente reintenta con la MISMA Idempotency-Key. ¿Qué debería hacer el servidor?
Devolver la respuesta original cacheada sin cobrar de nuevoCobrar la tarjeta de nuevo, porque llegó una nueva petición HTTPDevolver un error 500 para forzar al cliente a contactar soporteDescartar el reintento en silencio, sin respuesta
3. ¿Por qué el servidor debe guardar un hash del cuerpo de la petición junto con la clave de idempotencia?
Para detectar si la misma clave se está reutilizando para una petición genuinamente distinta, que debería rechazarse en vez de repetirsePara encriptar el número de tarjetaPara comprimir el payload al guardarloPara generar la clave misma