Integraciones API: reintentar sin duplicar acciones del negocio

Una integración API idempotente permite repetir una operación lógica sin crear otra acción del negocio. El caso difícil ocurre cuando vence el tiempo de espera después de que el sistema receptor ya actuó. La aplicación sabe que falta la respuesta; no sabe que la acción falló.

Resolver esa ambigüedad exige una identidad persistente para la operación y un camino de recuperación. Agregar únicamente un ciclo de reintentos aumenta el riesgo de duplicar acciones.

Identificá la acción, no cada intento

Creá una clave cuando la aplicación acepta la instrucción del negocio. Reutilizala en todos los intentos, incluso después de reiniciar un trabajador. Generar otra clave por solicitud HTTP elimina la posibilidad de reconocer la repetición.

Delimitá la clave por organización y tipo de acción. Guardá una huella de los parámetros previstos: reutilizar accidentalmente la clave con otros datos debe generar un conflicto. Protegé las solicitudes simultáneas con una restricción de unicidad en la base de datos o un mecanismo atómico equivalente.

El contrato del proveedor importa. La documentación de idempotencia de Stripe especifica que API v1 devuelve respuestas guardadas, incluidos ciertos errores, y describe límites de retención. Revisá versión y endpoint; no asumás que todos conservan claves indefinidamente o tratan igual las fallas.

El estado local debe sobrevivir a una caída

Mantené un registro con clave, huella de solicitud, estado, intentos y referencia de destino. Guardá la aceptación antes del envío en segundo plano. Si aceptar un cambio local también requiere programar una llamada externa, un patrón de bandeja de salida transaccional puede registrar ambas intenciones en la misma transacción.

Esa bandeja no garantiza una única ejecución remota. Permite recuperar el envío. El receptor todavía necesita detectar duplicados, o el emisor debe poder consultar el estado de destino antes de repetir una operación de resultado incierto.

Usá estados explícitos: pendiente, en curso, exitosa, fallida y resultado desconocido. Este último evita que soporte interprete cualquier respuesta ausente como autorización para iniciar otra acción.

Ejemplo hipotético: reintentar un envío

Una aplicación de bodega solicita a un transportista crear un envío. El transportista lo acepta, pero la respuesta se pierde. El trabajador reintenta con la misma clave. Si el proveedor cumple el contrato de idempotencia acordado, puede identificar la acción original y devolver el envío existente.

Si no ofrece ese contrato, consultá primero la referencia externa estable del pedido. Cuando la consulta no permite distinguir ausencia de visibilidad tardía, detené el flujo para conciliar. Un registro local de duplicados no impide que un sistema remoto cree dos envíos al recibir solicitudes independientes.

Situación	Acción siguiente
Solicitud inválida	Corregir la entrada; no repetir automáticamente
Falla transitoria con contrato seguro	Reintentar con espera creciente, variación aleatoria y la misma clave
Respuesta incierta por timeout	Conciliar o repetir según el contrato documentado
Misma clave con otros parámetros	Rechazar el conflicto

Probá la respuesta perdida

Simulá una respuesta perdida después del éxito, solicitudes simultáneas, una caída del trabajador y un reintento fuera del período de retención del proveedor. Verificá cuántos registros de negocio existen, no solo el estado HTTP. Aplicá el mismo criterio a los eventos recibidos por webhook.

En la próxima revisión, pedí una demostración de recuperación tras perder deliberadamente una respuesta. Ese ejercicio aporta un criterio de aceptación concreto para software a la medida y expone supuestos que una demostración exitosa no pone a prueba.