Idempotencia en APIs y webhooks: reintentos sin duplicados

El timeout no indica si la operación se ejecutó

Un cliente envía una solicitud para crear un pedido. El servidor la procesa, pero la respuesta se pierde. Si el cliente repite la llamada sin protección, puede crear un segundo pedido. La API necesita reconocer que la segunda petición pertenece a la misma operación lógica.

El RFC 9110 define la idempotencia como que varias peticiones idénticas tengan el mismo efecto previsto que una sola. El estándar considera idempotentes métodos como PUT y DELETE; un POST de negocio no se vuelve idempotente automáticamente por usar HTTP. Una clave de idempotencia es un contrato de aplicación que debes documentar y aplicar en el servidor.

Contrato mínimo de una clave

1. El cliente genera una clave opaca por operación lógica y la conserva al reintentar esa misma operación.
2. El servidor asocia la clave al usuario o tenant, al endpoint y a una huella de la solicitud normalizada.
3. La primera petición reserva la clave, ejecuta la operación y guarda el resultado identificable.
4. Una repetición con la misma clave y el mismo contenido devuelve el resultado registrado, en vez de repetir el efecto.
5. La misma clave con contenido distinto se rechaza de forma explícita; no se interpreta como una nueva operación.

Situación	Respuesta esperada del diseño
Cliente pierde la respuesta después de crear un pedido	Repetición devuelve el identificador del pedido original
Llega dos veces el mismo webhook	Un solo efecto de negocio; las siguientes entregas quedan reconocidas
La misma clave trae otro importe o cliente	Conflicto y registro para investigar
Dos copias llegan a la vez	Una obtiene la ejecución; la otra espera o recibe el estado definido
El servicio dependiente está caído	Reintento limitado, con espera, sin perder la clave original

Consistencia y límites

Si el efecto de negocio y el registro de idempotencia se guardan en la misma base de datos, intenta confirmarlos en una transacción coherente. Para enviar eventos o llamar a otro servicio, define cómo deduplicar esa etapa —por ejemplo, un identificador de operación en una outbox— porque la transacción local no hace atómica una acción remota.

Define cuánto tiempo se retienen las claves según la ventana real de reintentos y duplicados; no las elimines antes de que puedan volver a llegar mensajes. Guarda solo los datos necesarios, limita el acceso y no devuelvas resultados de otra cuenta por aceptar una clave global.

Prueba antes de producción

Ensaya: una petición normal; timeout simulado tras el commit; reintento con misma clave; misma clave con payload distinto; peticiones concurrentes; fallo antes y después del commit; y reentrega de webhook. Verifica tanto la respuesta como el número de efectos de negocio.

Este diseño complementa los patrones de resiliencia en microservicios, la arquitectura event-driven con Kafka y la integración de APIs.