Un emisor que reintenta una solicitud POST, lo más común, un proveedor de pagos o un remitente de webhook reintentando un callback que no está seguro de haber completado, puede terminar ejecutando la lógica de tu endpoint una segunda vez: una segunda fila insertada, un segundo correo enviado, un segundo cargo registrado. Enviar un encabezado Idempotency-Key evita eso.
Cómo funciona
Envía un encabezado Idempotency-Key único (cualquier cadena que el emisor genere, un UUID es típico) en una solicitud POST. Si una solicitud con esa clave exacta ya se ejecutó contra este endpoint, la respuesta almacenada de esa primera ejecución se devuelve inmediatamente, byte por byte, incluyendo su código de estado, la propia lógica de tu endpoint nunca se ejecuta una segunda vez. Una solicitud con una clave que no se había visto antes se ejecuta normalmente, y su respuesta se almacena entonces bajo esa clave para la próxima vez. Esto funciona automáticamente en todos los endpoints POST, no hay nada que activar, un emisor que nunca envía el encabezado no se ve afectado en absoluto.
Una respuesta reproducida lleva un encabezado Idempotency-Replayed: true, para que puedas distinguir ambos casos si lo necesitas.
Cuánto tiempo se recuerda una clave
24 horas desde la primera solicitud, la misma ventana que usan la mayoría de proveedores de pago para sus propios reintentos. Después de eso, la misma clave se trata como nueva de nuevo.
Una limitación conocida
Dos solicitudes enviadas con la misma clave genuinamente en el mismo instante pueden fallar ambas en encontrar la respuesta almacenada y ejecutar ambas la lógica de tu endpoint, no hay un bloqueo mantenido entre las dos, solo una respuesta almacenada después del hecho. En la práctica un reintento real (el emisor esperando un tiempo de espera o un error antes de volver a intentarlo) nunca se superpone así, solo dos solicitudes disparadas deliberadamente en paralelo lo harían.
Consejo: Esto combina bien con "Qué pasa cuando un endpoint falla a mitad de camino", entre la reversión automática al fallar y una respuesta reproducida al reintentar, un emisor puede reintentar un POST de forma segura sin preocuparse de escrituras duplicadas en ningún caso.