Reintentos, límites y duplicados en APIs de IA: cómo evitar que un fallo ejecute una acción dos veces

El problema: una respuesta perdida no equivale a una operación fallida

En una integración con una API de IA, un timeout suele describir un hecho limitado: el cliente no recibió una respuesta dentro del plazo configurado. No permite concluir, por sí solo, que el proveedor no recibió la solicitud, que no la procesó o que no inició una acción posterior. La conexión puede interrumpirse después de que el servidor acepte la petición; la respuesta puede perderse después de que la operación se complete; y un proceso local puede reiniciarse cuando el resultado ya existe fuera de él.

Esta distinción importa más cuando una salida de modelo activa efectos operativos. Repetir una generación de texto puede producir una respuesta distinta y consumir recursos, pero normalmente no cambia un sistema de negocio. Repetir una instrucción que envía un correo, crea una reserva, registra un pago, modifica un expediente o invoca una herramienta sí puede producir un efecto duplicado. La seguridad del flujo no debe depender de que el modelo devuelva el mismo texto ni de que una única llamada de red llegue siempre a buen término.

La semántica de HTTP ayuda a fijar el límite del problema: una petición idempotente es aquella cuyo efecto previsto en el servidor permanece equivalente aunque se ejecute más de una vez. Esto no significa que toda repetición sea gratuita, que la respuesta sea idéntica o que no haya registros adicionales. Significa que el efecto relevante debe poder aplicarse repetidamente sin cambiar el resultado final esperado. En flujos de IA, esa propiedad debe comprobarse tanto en la llamada al proveedor como, de forma independiente, en cada sistema externo que reciba una acción.

Un modelo mental: petición, operación lógica, intento, efecto y confirmación

Conviene separar cinco conceptos que suelen mezclarse. La operación lógica es la intención de negocio: por ejemplo, «emitir una respuesta estructurada para el expediente X» o «enviar una sola notificación de aprobación». La petición es un mensaje concreto enviado a una API. Un intento es cada envío de esa petición, incluido el primero y sus reintentos. El efecto externo es el cambio observable en un destino: un mensaje enviado, una fila creada o una compra confirmada. La confirmación es la evidencia que permite marcar la operación lógica como completada, rechazada o pendiente de revisión.

Un mismo identificador de operación debe unir todos los intentos que persiguen una única intención. Debe crearse antes de la primera llamada y persistirse fuera de la memoria del proceso, de modo que sobreviva a caídas, despliegues y trabajos en segundo plano. No use como identidad únicamente un identificador de petición devuelto por un proveedor: puede no existir si hubo un fallo temprano y, aunque exista, normalmente identifica un intento, no toda la intención de negocio.

Además del identificador de operación, conserve una clave de idempotencia estable para el receptor que la admita. La clave debe mantenerse al repetir la misma operación lógica y cambiar cuando cambie la intención. Generar una clave nueva en cada reintento anula la deduplicación. Reutilizar una clave para dos operaciones distintas puede hacer que una acción legítima se confunda con una repetida. El registro debe guardar la relación entre operación, intento, destino, clave usada y resultado observado.

Clasifique el riesgo antes de automatizar un reintento

No existe una política única adecuada para todas las llamadas. Clasificar la operación por su riesgo de repetición obliga a decidir qué se protege. Las lecturas o consultas sin efectos suelen admitir reintentos cuando el coste y la carga están controlados. La generación de texto sin efectos externos puede repetirse, pero el resultado puede variar; por tanto, la aplicación debe decidir si acepta una nueva salida, conserva una parcial o presenta el caso como pendiente.

Una escritura idempotente puede ser repetible si el destino garantiza que la misma clave representa la misma operación. Una escritura compensable puede requerir una reversión posterior, pero la compensación no convierte automáticamente el reintento en seguro: también puede fallar, llegar tarde o tener efectos propios. Las acciones irreversibles o difíciles de verificar requieren una barrera mayor, como confirmación humana, una reserva previa o una consulta fiable al sistema destino antes de actuar.

Esta clasificación debe aplicarse al flujo completo, no solo a la llamada al modelo. Un modelo puede generar correctamente una llamada a herramienta y, sin embargo, la herramienta puede haberse ejecutado antes de que se pierda la respuesta. La salida textual posterior no es evidencia suficiente de que el efecto se produjo exactamente una vez. La capa que ejecuta herramientas debe registrar y deduplicar la acción con sus propios controles.

Diseñe la idempotencia en dos fronteras

Deduplicar una llamada al proveedor y deduplicar un efecto de negocio son problemas relacionados, pero no equivalentes. Aunque una API de modelo acepte una clave de idempotencia, esa protección no prueba que una herramienta downstream, un proveedor de correo o un sistema de pagos haya aplicado su efecto una sola vez. Del mismo modo, una herramienta idempotente no elimina el coste ni la saturación de repetir innecesariamente una solicitud de inferencia.

La práctica más robusta es establecer dos fronteras. En la primera, el wrapper de la API registra la operación y asocia los intentos a una clave estable cuando el contrato del proveedor la soporte. En la segunda, el ejecutor de acciones externas usa un identificador de efecto propio y un almacén duradero de deduplicación. Antes de ejecutar, comprueba si ya hay una acción completada para esa operación; si la hay, devuelve el resultado existente. Si no la hay, registra el inicio de forma que un reinicio posterior permita continuar la investigación.

No invente capacidades de reconciliación que el contrato real no ofrece. Las fuentes disponibles describen prácticas generales de reintento y semántica HTTP, pero no documentan para cada API de IA una consulta universal de estado de operación ni una clave de idempotencia aplicable a todos los endpoints. Revise la documentación contractual del endpoint concreto antes de depender de cualquiera de esas funciones.

Política de reintentos: presupuesto, backoff y jitter

Una política segura expresa límites antes de que ocurra el error. Debe definir qué familias de fallos son candidatas a reintento, el máximo de intentos, un deadline global de la operación, una espera máxima aceptable y el coste máximo tolerado. El número de intentos por sí solo no basta: cinco reintentos pueden exceder el plazo del usuario, agotar una cuota o mantener ocupados trabajadores que deberían liberar capacidad.

Las respuestas de limitación de tasa y los errores transitorios del servidor pueden justificar una espera y un nuevo intento, siempre que la operación sea repetible y quede presupuesto. La documentación de OpenClaw indica que determinados SDK basados en Stainless pueden tratar como reintentables respuestas 408, 409, 429 y de la familia 5xx. Eso describe una política de SDK en ese contexto, no una regla universal para cualquier endpoint o efecto externo. Los errores que señalan una solicitud inválida, una autorización ausente o una condición de negocio no se corrigen repitiendo idénticos datos; requieren corregir la causa o detener el flujo.

Use retroceso exponencial para ampliar progresivamente el intervalo y jitter para que muchos clientes no vuelvan a intentarlo a la vez. AWS recomienda tanto el retroceso exponencial como la fluctuación aleatoria, además de limitar los reintentos y verificar la idempotencia antes de repetir. Si una respuesta indica cuánto esperar mediante una señal de reintento, respétela cuando sea válida y compatible con el deadline de la operación. Si la espera rebasa el presupuesto, deje constancia del motivo de aplazamiento o fallo, en lugar de seguir esperando sin límite.

Límites de tasa y saturación: el reintento también es carga

Un error 429 indica que la capacidad disponible o el límite aplicable no permite continuar en ese momento; no demuestra que aumentar la presión resolverá el problema. Reintentar inmediatamente puede convertir un incidente limitado en una tormenta de tráfico. Además, los intentos fallidos pueden contabilizar dentro de límites de tasa, por lo que una estrategia agresiva puede retrasar todavía más las operaciones válidas.

Controle la concurrencia en la cola de trabajo, no solo dentro de cada cliente. Establezca límites por proveedor, modelo, credencial y tipo de operación cuando corresponda. Reserve capacidad para reconciliar estados ambiguos y para operaciones prioritarias; de lo contrario, una oleada de reintentos puede impedir que el sistema determine qué ocurrió. El presupuesto debe incluir tiempo de cola, tiempo de conexión, tiempo de procesamiento y esperas entre intentos.

La guía de OpenAI sobre errores 429 recomienda retroceso exponencial con fluctuación cuando no hay una indicación de espera utilizable, y aconseja limitar tanto el número de reintentos como el tiempo total dedicado. Es importante diferenciar la limitación transitoria de otros problemas de cuenta o cuota que no se arreglan esperando. La decisión debe basarse en la información del error y en el contrato de la integración, no solo en el código de estado.

Estados ambiguos: reconciliar antes de repetir

El estado ambiguo aparece cuando no hay confirmación suficiente para decidir si el efecto ocurrió. Debe ser un estado explícito y persistente, no una excepción que se borra al reiniciar un proceso. Registre al menos el identificador de operación, los datos o un resumen seguro de la intención, los identificadores de intento, las marcas temporales, la clave de idempotencia, el destino, la categoría de error y cualquier identificador devuelto antes del corte.

La reconciliación sigue una jerarquía. Primero, use una consulta de estado o un identificador de recurso si el contrato del receptor lo proporciona. Después, busque el efecto en el sistema destino con un criterio estable, como el identificador de operación incluido en metadatos. Si la evidencia confirma el efecto, cierre la operación sin repetir. Si prueba que no se aplicó, podrá abrir un nuevo intento conforme a la política. Si no permite distinguir ambos casos, no suponga ausencia: mantenga el caso pendiente y escálelo cuando el riesgo lo justifique.

La revisión humana no es un fallo del diseño; es un control de seguridad para operaciones cuyo coste de duplicación supera el coste de demora. Las condiciones de escalado deben ser concretas: cargos financieros, comunicaciones irreversibles, modificación de registros regulados, inconsistencia entre fuentes, vencimiento del deadline o ausencia de una prueba fiable de deduplicación.

Patrones para salidas estructuradas, herramientas y agentes

Para salidas estructuradas, separe la validación de la ejecución. Una respuesta que no cumple el esquema no debe alimentar directamente una herramienta. Guarde la salida recibida, valide tipos, campos obligatorios, rango de valores y autorización de la acción propuesta. Si decide pedir una nueva generación, trátela como un nuevo intento de producir un plan, no como prueba de que ninguna herramienta se ejecutó antes.

En tool calling, el controlador debe ser la autoridad sobre la ejecución. El modelo puede proponer una llamada, pero el controlador debe asignar el identificador de operación, comprobar permisos, deduplicar argumentos semánticamente equivalentes cuando proceda y registrar el resultado. Si el agente reanuda tras una caída, debe recuperar el registro de herramientas ya ejecutadas; no debe inferir el historial a partir del texto de una conversación.

Para agentes con múltiples pasos, evite reintentar el flujo compuesto entero como una unidad opaca. Reintente pasos individuales solo cuando se conozcan sus límites y sus garantías. Una planificación puede regenerarse; una lectura puede repetirse con advertencia de datos cambiantes; una escritura debe reconciliarse; y una acción irreversible requiere una barrera explícita. Este diseño reduce duplicados y también mejora la auditabilidad cuando el sistema recibe resultados parciales.

Checklist de producción y límites de esta guía

Antes de activar reintentos automáticos, documente para cada operación su dueño, destino, efectos, coste de duplicación, clave de idempotencia, evidencia de confirmación, deadline, número máximo de intentos y condición de escalado. Pruebe caídas en cada frontera: antes de enviar, durante la transmisión, después de que el destino acepte la petición y antes de persistir la respuesta local. Una prueba útil verifica que un reinicio del proceso no crea un segundo efecto.

Revise también la arquitectura en el contexto del centro de aprendizaje, la documentación de seguridad, los criterios de precios y el glosario de su producto. El límite de reintentos afecta al coste y a la latencia; la retención de registros afecta a la privacidad; y las credenciales usadas para reconciliar o ejecutar herramientas deben tener privilegios mínimos. Para modelos concretos, como GPT-6 Astra, y para integraciones de una organización como OpenAI, la política final debe ajustarse al contrato y a las capacidades efectivamente documentadas para el endpoint utilizado.

La regla de cierre es sencilla: no declare éxito por haber emitido una solicitud, ni declare ausencia de efecto por no haber recibido una respuesta. Declare una operación resuelta solo cuando la evidencia persistida permita sostener su estado. Cuando esa evidencia no exista, la decisión segura puede ser esperar, reconciliar o pedir intervención humana.

Continúa explorando

Correcciones y transparencia

Si detectas un dato incorrecto o desactualizado, puedes enviarnos una corrección indicando la página y la fuente que debemos revisar.