APIs con reintentos seguros: evita duplicados cuando la red falla

Un cliente envía una operación, espera demasiado y recibe un timeout. No sabe si el servidor rechazó la petición, si la completó o si sigue trabajando. Repetirla parece una solución razonable, pero puede crear dos recursos o ejecutar dos veces una acción. Esa incertidumbre es normal en una integración distribuida. La idempotencia permite diseñar operaciones cuyo efecto previsto no se multiplica al repetir la misma solicitud, siempre dentro de un contrato explícito y correctamente implementado.

Distingue repetir una intención de crear otra nueva

Dos peticiones con los mismos datos no representan necesariamente la misma operación. Una persona puede querer crear dos tareas idénticas. Por eso suele ser útil que el cliente asigne una clave única a cada intención y la conserve en sus reintentos. El servidor relaciona esa clave con el cliente autorizado y la operación correspondiente. No uses una clave global sin contexto, porque clientes distintos podrían colisionar o acceder a información que no les corresponde.

Define el contrato antes de implementar la caché

Especifica qué operaciones admiten la clave, cuánto tiempo se conserva y qué respuesta obtiene una repetición. Decide qué ocurre si alguien reutiliza la misma clave con parámetros diferentes: normalmente debe rechazarse como un conflicto de intención. Explica también el comportamiento mientras la primera petición sigue en curso. El cliente necesita saber si debe esperar, consultar el estado o volver a intentar después. Una cabecera sin estas reglas no constituye una garantía suficiente.

La conservación importa porque un reintento tardío puede llegar después de eliminar el registro de deduplicación. Ajusta el plazo al proceso y documenta esa limitación. Para operaciones especialmente sensibles, puede ser necesario un identificador de negocio único adicional o un mecanismo de conciliación. La idempotencia técnica de una ventana temporal y la regla de negocio que impide duplicados durante años son problemas relacionados, pero no intercambiables.

Resuelve la concurrencia y los fallos intermedios

Dos solicitudes con la misma clave pueden llegar al mismo tiempo. Comprobar primero si existe y escribir después, sin protección, permite que ambas avancen. Utiliza restricciones únicas, transacciones o mecanismos equivalentes adecuados al almacenamiento. Además, coordina el registro de la clave con el efecto de la operación: guardar uno sin el otro deja estados ambiguos. La explicación de Amazon Builders’ Library sobre APIs idempotentes aborda precisamente esta necesidad de coherencia entre intención registrada y mutaciones.

• Genera una clave por operación lógica y mantenla en todos sus reintentos.
• Asocia la clave al cliente, al tipo de operación y a los parámetros relevantes.
• Protege la creación concurrente del registro y define estados en curso y terminados.
• Prueba fallos antes y después de cada efecto persistente, no solo respuestas exitosas.

No todos los efectos caben en una transacción

Una operación puede escribir en una base de datos y después llamar a otro servicio. La transacción local no cubre automáticamente esa llamada externa. Diseña una entrega fiable y una identificación que permita al receptor deduplicar cuando sea posible. Conserva estado suficiente para reconciliar resultados inciertos. Evita anunciar ejecución exactamente una vez de extremo a extremo si no puedes justificarla: en sistemas distribuidos, las garantías reales dependen de todos los participantes y de sus límites.

Limita los reintentos para no agravar una caída

La idempotencia reduce duplicados, pero no evita que miles de reintentos saturen un servicio. Establece un máximo de intentos, tiempo total y esperas crecientes con variación aleatoria cuando corresponda. Respeta las indicaciones del servidor y revisa qué hace ya el SDK para no superponer varias políticas. Un error de validación no suele resolverse repitiendo exactamente la petición. Clasifica errores y conserva una salida visible cuando la operación requiere intervención o conciliación.

El usuario también necesita un estado comprensible. Desactivar un botón durante el envío puede mejorar la experiencia, pero no sustituye la protección del servidor. Tras un fallo de red, muestra que la operación está pendiente de confirmación en vez de afirmar que no ocurrió. Si existe una consulta por identificador, úsala para recuperar el resultado. Esta coherencia entre interfaz y contrato evita que la persona genere nuevas intenciones intentando solucionar una respuesta incierta.

Prueba el comportamiento que más cuesta reproducir

Incluye pruebas de concurrencia, respuesta perdida después de confirmar, claves reutilizadas con cambios y reintentos al vencer la conservación. Registra identificadores de correlación sin almacenar secretos ni contenido innecesario. Estas pruebas ofrecen más valor que comprobar únicamente una petición duplicada secuencial. Una API fiable no presupone una red perfecta: explica sus garantías, conserva evidencia de cada intención y permite recuperar resultados sin multiplicar los efectos de una operación importante.