Diseñar operaciones idempotentes y reintentos seguros

Objetivo

Un cliente cuya solicitud termina en un tiempo de espera agotado debe poder reintentarla sin riesgo: sin pedido duplicado, sin pago duplicado, sin artículo duplicado.

Requisitos previos

El RFC 9110 llama idempotente a un método cuando el efecto pretendido de varias solicitudes idénticas en el servidor es el mismo que el de una sola; PUT, DELETE y los métodos seguros (GET, HEAD, OPTIONS, TRACE) lo son, POST no. El mismo RFC establece que un cliente no debe reintentar automáticamente una solicitud con un método no idempotente, salvo que sepa que la semántica es en realidad idempotente. Para POST, el borrador del IETF «The Idempotency-Key HTTP Header Field» (grupo de trabajo HTTPAPI; versión 07 de octubre de 2025, caducado en septiembre de 2026 y no publicado como RFC) describe la cabecera que emplean Stripe y otros proveedores. Se necesitan un almacén para un pequeño conjunto de datos por clave y clientes que generen una clave única por operación lógica.

Pasos

1. Elegir los métodos según el RFC 9110: modificar mediante PUT sobre una dirección conocida, eliminar mediante DELETE; ambos pueden reintentarse sin mecanismo adicional.
2. Para las solicitudes POST que crean algo, aceptar una cabecera Idempotency-Key. El borrador recomienda un UUID o un identificador de aleatoriedad comparable; Stripe propone UUID v4, permite hasta 255 caracteres y desaconseja usar datos sensibles como clave.
3. En la primera llegada, guardar la clave junto con una huella de la solicitud (hash sobre la ruta y el cuerpo), la cuenta y el resultado (estado, cuerpo de respuesta), dentro de la misma transacción que la propia operación o bajo un bloqueo sobre la clave, para que dos reintentos simultáneos no pasen ambos.
4. Ante una clave repetida con la misma huella, devolver la respuesta guardada sin cambios. Ante la misma clave con un cuerpo distinto, responder 422, como prevé el borrador; si la solicitud original sigue en curso, responder 409.
5. Eliminar las claves tras un plazo documentado; Stripe describe una eliminación a partir de las 24 horas como mínimo y trata una clave reutilizada después como una solicitud nueva.
6. Dejar constancia del formato de clave, el plazo y el comportamiento ante conflictos en la documentación de la API, para que los clientes y los agentes puedan confiar en ello en lugar de adivinar.

Resultado esperado

Un cliente que reintenta con la misma clave tras un tiempo de espera agotado obtiene exactamente un recurso creado y dos veces la misma respuesta.

Límites y base de verificación

La idempotencia cubre el estado del propio servidor, no los efectos secundarios en sistemas ajenos (un correo enviado dos veces por un servicio aguas abajo). Las claves deben mantenerse separadas por cuenta, o los clientes chocarán entre sí. El borrador no es un RFC y actualmente está caducado; las afirmaciones sobre la cabecera y los códigos de estado siguen el borrador y la documentación de Stripe citada; no se afirma ninguna medición.