Lo que aprenderás en esta guía
Este es un artículo técnico y profundo redactado por los ingenieros de ForgeNEX. Está diseñado para profesionales que buscan implementar soluciones sólidas y evitar los errores comunes que cuestan horas de producción.
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
- El cliente genera una clave opaca por operación lógica y la conserva al reintentar esa misma operación.
- El servidor asocia la clave al usuario o tenant, al endpoint y a una huella de la solicitud normalizada.
- La primera petición reserva la clave, ejecuta la operación y guarda el resultado identificable.
- Una repetición con la misma clave y el mismo contenido devuelve el resultado registrado, en vez de repetir el efecto.
- 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.
¿Demasiado complejo para tu equipo?
En ForgeNEX gestionamos este tipo de soluciones tecnológicas todos los días. Evita riesgos y delega la implementación en nuestros expertos.
- Respuesta en menos de 2 horas
- Auditamos tu caso sin compromiso
- Expertos certificados