Qué es la idempotencia en una API y cómo evita duplicados

Una operación es idempotente cuando una petición se repite una o varias veces y el efecto previsto sobre el servidor queda igual que después de una sola ejecución. La respuesta puede variar por el momento o incluir metadatos nuevos, pero el estado que importa para la operación no debe multiplicarse.

También puede servirte: Qué es un rate limit en una API y cómo aplicarlo

La propiedad no describe si una petición es segura o si siempre devuelve el mismo código. Describe qué ocurre con el efecto acumulado. Por eso una lectura suele ser idempotente y una creación de recurso normalmente necesita una estrategia adicional si el cliente puede reintentarla.

Un cliente puede enviar una petición, perder la respuesta y no saber si el servidor terminó el trabajo. Si vuelve a enviarla sin una identidad para esa intención, la API puede crear dos órdenes, dos reservas o dos cargos. El corte no prueba que la primera ejecución haya fallado.

La solución empieza por distinguir un reintento de una nueva operación. El cliente genera una clave única para esa intención y la conserva mientras repite la petición. El servidor registra la clave junto con el resultado y devuelve el mismo resultado cuando recibe de nuevo esa clave válida.

La clave debe ser única dentro del alcance que la API puede controlar y no debe cambiar entre reintentos de la misma acción. También conviene asociarla al usuario, cuenta o recurso que la ejecuta, validar que el cuerpo de la petición coincida y conservar el resultado durante una ventana documentada.

Una clave no reemplaza la autorización ni la validación del pedido. El servidor debe comprobar permisos, importes y estado antes de ejecutar. Si una segunda petición usa la misma clave con parámetros diferentes, hay que rechazarla para que una identidad de operación no termine representando dos intenciones.

Definí qué efecto debe quedar una sola vez: crear un registro, confirmar un pago o publicar un evento. Después elegí dónde se guarda la clave y el resultado, qué pasa si dos reintentos llegan al mismo tiempo y cuánto dura la ventana de deduplicación. La respuesta debe permitir al cliente saber si puede continuar.

También documentá qué métodos y endpoints aceptan reintentos y cuál es el comportamiento ante una clave vencida. Las pruebas deben cubrir un corte después de que el servidor persiste el resultado, dos peticiones concurrentes y una repetición con parámetros distintos. Así la idempotencia se comprueba en el límite donde realmente aparecen los duplicados.