Diseñar idempotencia, reintentos y timeouts

Los sistemas distribuidos fallan de maneras ambiguas. Una petición puede no llegar, llegar tarde, ejecutarse correctamente y perder su respuesta o ejecutarse dos veces porque el cliente reintentó. La fiabilidad del workflow depende menos de “que nunca haya errores” que de definir qué ocurre cuando aparecen.

La idempotencia es una propiedad clave para controlar repeticiones. En HTTP, un método se considera idempotente cuando múltiples peticiones idénticas tienen el mismo efecto previsto sobre el servidor que una sola. En operaciones de negocio creadas sobre APIs, a menudo se utilizan claves de idempotencia para reconocer la misma intención cuando el cliente necesita repetir una petición.

Clasifica cada operación por su efecto

Antes de configurar reintentos, pregunta qué cambia la operación.

Una lectura puede repetirse con menos riesgo que una creación de pedido, un cobro o un envío de correo. Incluso una operación aparentemente inocua puede tener efectos secundarios: consultar un endpoint podría registrar una acción o consumir una cuota.

Clasifica al menos:

• solo lectura;
• escritura reversible;
• escritura irreversible o costosa;
• acción externa, como enviar un mensaje;
• operación de larga duración.

La política de fallo no debe ser la misma para todas.

Diseña una identidad de intención

Si una operación puede repetirse, necesitas saber cuándo dos solicitudes representan la misma intención empresarial.

Una clave de idempotencia no debería generarse de nuevo en cada reintento. Debe permanecer estable mientras el cliente intenta completar la misma acción. Puede derivarse de un identificador del caso y de la operación, o crearse explícitamente y persistirse.

Ejemplo conceptual:

REQ-2026-0042:crear-presupuesto:v3

Si el usuario modifica el contenido y solicita una nueva versión, cambia la intención y debería existir otra clave.

Diferencia errores transitorios de permanentes

Un timeout, una saturación temporal o un 503 pueden justificar reintento. Un error de validación, una autorización denegada o un identificador inexistente normalmente no se corrigen esperando cinco segundos.

Define una taxonomía de errores por integración. El workflow debe saber cuáles son:

• reintentables;
• no reintentables;
• inciertos;
• recuperables mediante intervención humana.

No conviertas “catch error → retry” en una política universal.

Limita y espacia los reintentos

Reintentar inmediatamente y sin límite puede empeorar una incidencia. Los patrones de retry con backoff introducen espera progresiva entre intentos; en muchos sistemas también se añade jitter para reducir sincronización entre clientes.

La configuración depende del servicio y del objetivo. Define:

• número máximo de intentos;
• espera inicial;
• incremento o backoff;
• límite total de tiempo;
• errores incluidos;
• qué estado recibe el caso al agotarse los intentos.

No uses valores “estándar” sin medir la dependencia real.

Define timeouts por operación

Un timeout no es un fallo del sistema remoto; es una decisión del cliente de dejar de esperar. La operación remota puede seguir ejecutándose.

Por eso un timeout en una acción mutadora genera incertidumbre. Antes de repetir, intenta determinar si el efecto ocurrió mediante un identificador, consulta de estado o clave de idempotencia.

Los timeouts deben considerar latencia normal, percentiles observados y experiencia aceptable del proceso. Una consulta interactiva y una generación de documento larga pueden necesitar límites muy distintos.

Diseña reconciliación

Algunos fallos no pueden resolverse durante la ejecución original. Necesitas un proceso posterior que compare estados y repare discrepancias.

Ejemplo: el workflow marcó envio_incierto, pero el proveedor de correo registra el mensaje como entregado a su servicio. Un reconciliador puede actualizar el caso y evitar un segundo envío.

La reconciliación es especialmente importante cuando intervienen sistemas sin transacción común.

Ejemplo: enviar un presupuesto

Imagina que el workflow llama a un servicio para enviar un presupuesto y la conexión se interrumpe después de que el servicio acepte la petición. El cliente no sabe si el mensaje salió.

Una estrategia robusta podría ser:

1. crear una operación con identificador estable;
2. registrar envio_pendiente;
3. enviar utilizando esa identidad;
4. si hay timeout, consultar estado;
5. reintentar solo si la operación no consta como procesada;
6. si persiste la incertidumbre, pasar a revisión.

El objetivo no es garantizar matemáticamente “exactly once” en cualquier infraestructura, sino controlar duplicados y estados ambiguos de acuerdo con las capacidades reales.

Ejercicio: política de fiabilidad

Selecciona cinco interacciones del workflow. Para cada una documenta:

• efecto;
• idempotente por naturaleza: sí/no/no seguro;
• clave de intención, si procede;
• timeout;
• errores reintentables;
• máximo de reintentos;
• backoff;
• consulta de estado;
• reconciliación;
• estado final cuando no puede recuperarse.

Incluye al menos una operación que no deba reintentarse automáticamente.

Resultado de la lección

El workflow ya tiene un comportamiento diseñado ante respuestas tardías, duplicados y fallos transitorios. Los reintentos dejan de ser una reacción genérica y se convierten en una política ligada a efectos, identidad y recuperación. La siguiente lección se ocupará de los casos que no pueden resolverse automáticamente y necesitan excepción, aprobación o escalado.