
Cómo diseñar una API idempotente para evitar operaciones duplicadas
Cuando una petición termina por tiempo de espera, el cliente puede no saber si el servidor llegó a ejecutar la operación. Un contrato de idempotencia permite reconocer los reintentos de una misma intención y controlar sus efectos dentro de un ámbito y un plazo definidos.
Qué significa idempotencia en HTTP
Según el RFC 9110, sección 9.2.2, la idempotencia se refiere al efecto pretendido en el servidor: varias solicitudes idénticas tienen el mismo efecto pretendido que una sola, aunque sus respuestas puedan ser distintas. El RFC considera idempotentes PUT, DELETE y los métodos seguros. También desaconseja reintentar automáticamente un método no idempotente salvo que se sepa que su semántica es idempotente o que la solicitud original no se aplicó.
Para un POST que crea un pago, una clave de idempotencia puede ayudar a que los reintentos sean seguros. Su protección depende del contrato y de cómo se implemente, tanto en el servidor como en sus integraciones.
Elegir y conservar la clave
El cliente genera una clave por cada operación lógica y reutiliza esa misma clave en los reintentos. Si quiere crear otro pago, utiliza una clave nueva, aunque los parámetros sean idénticos. AWS explica que dos solicitudes con los mismos parámetros pueden representar dos intenciones distintas y describe el uso de un identificador único aportado por el cliente.
Para generar la clave, Stripe recomienda UUID v4 u otra cadena aleatoria con suficiente entropía y aconseja evitar datos sensibles, como direcciones de correo e identificadores personales. En el párrafo sobre generación de claves, la documentación dice “we suggest using V4 UUIDs” y “Avoid using sensitive data”. Como pauta práctica, el cliente debe conservar la clave junto con la operación pendiente para poder reutilizarla después de un fallo o reinicio.
Una opción es enviar el identificador en la cabecera Idempotency-Key, objeto de un borrador IETF para métodos como POST y PATCH. El estado del borrador puede cambiar; documenta en cualquier caso el formato y el comportamiento que admite tu API.
Registrar la operación en el servidor
Como diseño práctico, asocia cada clave con el cliente autenticado y el ámbito de la operación. Guarda también los parámetros relevantes o una huella de estos, el estado de ejecución y el resultado necesario para responder a los reintentos. Si usas una huella normalizada, especifica qué diferencias de representación considera equivalentes el contrato.
Si la misma clave llega con parámetros incompatibles, rechaza la solicitud y explica el conflicto. En la sección Same client request ID, different intent, AWS describe que conserva los parámetros iniciales y devuelve un error de validación ante una discrepancia. Delimitar además la clave por operación y elegir cómo normalizar los parámetros son decisiones de diseño que deben documentarse.
Controlar solicitudes concurrentes
Dos reintentos pueden llegar antes de que termine el primero. Una restricción única sobre el cliente, el ámbito y la clave es una opción para impedir que ambos inicien la misma operación local. La reserva de la clave y las mutaciones locales relacionadas deben coordinarse atómicamente: en Reducing client complexity, AWS plantea que registrar el identificador y realizar esas mutaciones cumpla las propiedades ACID como una operación de todo o nada.
El contrato también debe indicar qué ocurre si llega un duplicado mientras el primero sigue en curso. Por ejemplo, la API podría informar de que la operación está pendiente y explicar cómo consultar su resultado o reintentar más adelante. El código de respuesta y los tiempos son decisiones de la implementación.

Definir respuestas, errores y caducidad
Cuando la operación termina, la API puede devolver el resultado guardado o una respuesta semánticamente equivalente, según su contrato. En Retries and semantic equivalence, AWS propone una respuesta semánticamente equivalente para el mismo identificador durante un intervalo. Documenta también qué errores se guardan y cuáles permiten volver a ejecutar trabajo.
Las políticas concretas pueden diferir. Stripe documenta para API v1 que guarda el código de estado y el cuerpo de la primera solicitud una vez iniciada la ejecución del endpoint: “after endpoint execution begins”. Devuelve esa respuesta en los reintentos, incluidos errores 500. Si falla la validación o hay un conflicto con una solicitud concurrente antes de que empiece la ejecución, no guarda el resultado.
En cambio, la sección Idempotency de la descripción de API v2 de Stripe indica que, si la primera solicitud tuvo éxito, “skips making new changes” y “returns an updated response”. Si falló total o parcialmente, reejecuta el trabajo fallido cuando es posible; si ya no puede completar la repetición, devuelve un error explicativo. La repetición requiere la misma clave y API, la misma cuenta o sandbox y un intervalo de 30 días. Estas son políticas de Stripe, no reglas generales.
Publica el plazo de retención y el comportamiento de los reintentos tardíos. Por ejemplo, Stripe indica que en v1 pueden eliminarse claves de al menos 24 horas y que reutilizar una clave eliminada genera una solicitud nueva. Un cliente necesita conocer el plazo de su propia API y qué hacer cuando ya no puede determinar con seguridad el resultado anterior.
Proteger también los efectos externos
Una transacción local no demuestra por sí sola que un proveedor de pagos o un sistema de mensajería haya procesado una operación una sola vez. Como recomendación de diseño, propaga identificadores estables, utiliza la deduplicación que admita cada sistema y prevé la reconciliación cuando el resultado externo sea incierto. Esta recomendación se deriva de la incertidumbre de las operaciones distribuidas que analiza AWS, donde un tiempo de espera puede dejar sin resolver si se creó un recurso.
Lista de comprobación del contrato
- Definir quién genera la clave, dónde se envía y cuándo debe cambiar.
- Especificar el ámbito por cliente y operación, y cómo se detectan parámetros incompatibles.
- Describir el comportamiento ante solicitudes concurrentes, resultados terminados y errores.
- Publicar la retención y la política para reintentos tardíos.
- Explicar cómo se manejan los efectos externos y los resultados inciertos.
Estas pautas orientan el diseño. No se ha evaluado una implementación concreta: la ausencia de duplicados depende de la API, sus integraciones y el contrato de cada sistema participante.
Comentarios
Publicar un comentario