Tu agente llama a una API. La API devuelve un 429. Tu agente reintenta de inmediato, obtiene otro 429, reintenta de nuevo, y ahora tienes un bucle que golpea un servicio limitado hasta que la ejecución falla o la factura se dispara. Nadie escribió ese bucle a propósito. Surge de la versión ingenua de "manejar el error", y es lo más común que los desarrolladores preguntan en el foro de discusión del SDK de Anthropic.
La recuperación de errores es la parte de la construcción de agentes que separa una demostración limpia de algo por lo que puedes llamar a alguien. El modelo no es el problema. El problema es lo que hace tu código cuando una llamada a una herramienta regresa lenta, limitada o rota. Si la recuperación es correcta, una dependencia inestable se convierte en una breve pausa que el usuario nunca nota. Si lo haces mal, un solo 500 se convierte en un incidente. Esta guía cubre los cuatro patrones que soportan la mayor parte de la carga: reintentos con retroceso exponencial, tiempos de espera, disyuntores e claves de idempotencia. Luego, muestra cómo probarlos contra un simulacro, antes de que un usuario encuentre las brechas por ti. Para una visión más amplia de cómo fallan los agentes, comienza con por qué los agentes de IA fallan en producción.
No puedes probar la recuperación contra una API sana
Aquí está la trampa. Tu dependencia funciona bien en desarrollo. Escribes tu agente, las llamadas tienen éxito, la demostración es limpia y lo lanzas. El código de recuperación nunca se ejecutó, porque una API sana nunca devuelve los errores que se supone que debe manejar. La primera vez que tu lógica de retroceso se ejecuta es en producción, contra una interrupción real, con usuarios reales observando. Ese es el peor lugar para descubrir un error tipográfico en un bucle de reintentos.
Así que la regla es simple. Para probar la recuperación, produces los fallos a propósito. Levanta un simulacro de la API a la que llama el agente, prográmalo para que devuelva un 429, un 500, un tiempo de espera o un cuerpo malformado, apunta el agente hacia él y observa lo que hace. El fallo se convierte en algo que tú activas en una prueba en lugar de algo que te activa a las 3 de la mañana. Apidog configura ese simulacro y programa las respuestas, y lo repasa en la sección de pruebas al final.
Reintentos con retroceso exponencial y fluctuación
Un reintento es la primera línea de defensa, y la versión ingenua es la trampa. Captura el error, vuelve a llamar inmediatamente. Contra un fallo transitorio, eso funciona. Contra un servicio bajo carga, empeora las cosas, porque cada cliente fallido reintenta en el mismo instante y la estampida mantiene el servicio caído.
Dos soluciones se combinan. El retroceso exponencial espacia los intentos: espera 1 segundo, luego 2, luego 4, luego 8, duplicando hasta un límite. El servicio tiene espacio para recuperarse en lugar de una avalancha de reintentos inmediatos. La fluctuación (jitter) añade un desplazamiento aleatorio a cada espera para que mil clientes que fallaron al mismo tiempo no reintenten todos al mismo tiempo. Sin ella, el retroceso seguiría produciendo ondas sincronizadas.
Limita dos cosas: el retraso, para no esperar minutos entre intentos, y el número de intentos, para que un fallo permanente se rinda en lugar de reintentar para siempre. Entre tres y cinco intentos cubren casi todos los errores transitorios. Más allá de eso, generalmente estás reintentando algo que no va a tener éxito. El SDK de Anthropic hace parte de esto para sus propias llamadas: reintenta errores de conexión y códigos de estado específicos con retroceso exponencial, y tú estableces el límite con una opción de reintentos máximos. No cubre las otras APIs a las que acceden las herramientas de tu agente, así que debes envolverlas tú mismo. Los equipos que manejan dinero a través de sus reintentos aprenden esto temprano, y nuestro desglose de la lógica de reintentos para APIs de alto riesgo muestra dónde un reintento descuidado causa un daño real.
Establece un tiempo de espera en cada llamada
Un reintento solo ayuda si la solicitud falla. El caso más desagradable es una solicitud que nunca regresa: una dependencia acepta tu conexión y luego se cuelga. Sin tiempo de espera, la llamada a la herramienta se bloquea y toda la ejecución se detiene detrás de un socket muerto. Sin error, sin recuperación, solo un agente atascado quemando tiempo de reloj y presupuesto de tokens en nada.
Cada llamada saliente necesita un tiempo de espera. Establece un tiempo de espera de conexión para establecer la conexión y un tiempo de espera de lectura para esperar la respuesta, luego un presupuesto total para toda la ejecución del agente para que una cadena de llamadas lentas pero legales no agote la paciencia del usuario. Cuando se activa un tiempo de espera, trátalo como cualquier otro error reintentable: retrocede y vuelve a intentarlo, hasta tu límite.
Elige los números de la latencia real, no por adivinación. Establece cada tiempo de espera por encima del p99 de la dependencia con un margen. Demasiado ajustado y abortarás llamadas que habrían tenido éxito. Demasiado holgado y una dependencia colgada mantendrá al agente ocupado mucho más allá del punto de utilidad. Asigna a las respuestas de streaming su propio presupuesto, ya que una finalización larga es legítimamente lenta y un tiempo de espera fijo corto la interrumpe a mitad de la transmisión.
Activa un disyuntor cuando una dependencia está caída
El retroceso maneja un servicio que está brevemente ocupado. Es la herramienta equivocada para un servicio que está completamente caído. Si una dependencia ha estado fallando durante un minuto, la siguiente solicitud casi con certeza también fallará, y reintentarla acumula más carga sobre algo que ya está roto mientras el usuario espera un fallo que podrías haber predicho.
Un disyuntor soluciona esto con tres estados. Cerrado es normal: las solicitudes fluyen y el disyuntor cuenta los fallos. Cuando los fallos superan un umbral, se dispara a abierto: deja de enviar solicitudes y falla rápidamente durante un período de enfriamiento, para que no pagues el tiempo de espera en cada llamada a un servicio inactivo. Después del período, pasa a semiabierto y permite el paso de una única sonda. Si la sonda tiene éxito, el disyuntor se cierra y el tráfico se reanuda; si falla, se abre de nuevo y espera.
Para un agente, el disyuntor convierte "la API de pago está caída" en un fallo rápido y limpio sobre el que el agente puede razonar, en lugar de cuarenta tiempos de espera lentos que agotan el presupuesto de tokens y el reloj. Conéctalo por dependencia, no globalmente, para que una API de búsqueda inactiva no impida que el agente utilice una API de facturación saludable.
Haz los reintentos seguros con claves de idempotencia
Todos los patrones hasta ahora asumen que reintentar es seguro. A menudo no lo es. Tu agente envía POST /charge, el servidor lo procesa y la respuesta agota el tiempo de espera en el camino de regreso. El agente nunca vio el éxito, por lo que reintenta, y ahora al cliente se le cobra dos veces. El reintento hizo exactamente lo que le pediste. El diseño fue el error.
Una clave de idempotencia cierra la brecha. El cliente genera una clave única por acción lógica y la envía con la solicitud, generalmente como un encabezado Idempotency-Key. El servidor registra la clave al recibirla por primera vez y, si vuelve a ver la misma clave, devuelve el resultado original en lugar de realizar el trabajo dos veces. Ahora un reintento es seguro por construcción: el segundo POST /charge con la misma clave es una operación nula que devuelve el primer cargo.
La clave debe permanecer estable en los reintentos de la misma acción y cambiar entre diferentes acciones. Genérala una vez cuando construyas la solicitud, no dentro del bucle de reintentos, o cada intento obtendrá una clave nueva y la deduplicación nunca se activará. Cualquier llamada a herramienta que cree o cambie el estado (cargos, pedidos, correos electrónicos, registros) necesita una. Nuestra guía sobre claves de idempotencia cubre la generación y el manejo del lado del servidor en su totalidad.
Sobrevive a los límites de tasa y al bucle RateLimitError
Los límites de tasa merecen su propio manejo porque vienen con instrucciones. Una respuesta de límite de tasa excedido generalmente llega como un 429 con un encabezado Retry-After que te dice exactamente cuánto tiempo esperar, en segundos o como una fecha. Respétalo. Si el servidor dice que esperes 30 segundos y reintentas en 2, obtienes otro 429, y has construido el bucle RateLimitError que llena el foro de discusión del SDK: atrapa el límite, reintenta demasiado pronto, sé limitado con más fuerza, repite hasta que la ejecución termine. Un hilo del SDK separado cubre el mismo obstáculo que los desarrolladores encuentran aquí.
La solución es dejar que el servidor marque el ritmo. Cuando recibas un 429, lee Retry-After y espera al menos ese tiempo antes de reintentar. Si el encabezado falta, recurre al retroceso exponencial con fluctuación. Limita los intentos para que un límite sostenido termine en un fallo limpio en lugar de una espera infinita. El SDK de Anthropic ya respeta Retry-After para sus propias llamadas; el trabajo consiste en aplicar la misma regla a las otras APIs con límite de tasa que toca tu agente.
También hay un lado proactivo. Si un proveedor permite un número determinado de solicitudes por minuto, mide tus propias llamadas con un cubo de tokens para mantenerte por debajo del límite en lugar de encontrarlo al ser limitado. La recuperación maneja los límites que alcanzas; la regulación evita que los alcances.
Cómo probar la ruta de recuperación
Ahora, únelo todo. Los patrones anteriores son tan buenos como la prueba de que funcionan, y la prueba es un test que fuerza los fallos que una API sana no te dará. La estructura se reutiliza en cada escenario:
- Simula la dependencia. Configura un simulacro de la API a la que llama la herramienta de tu agente, para que controles cada código de estado, encabezado, cuerpo y retraso, y ninguna carga o correo electrónico real se dispare durante la prueba.
- Programa una secuencia. Programa el simulacro para que responda a una serie de llamadas en orden: primero un 429 con
Retry-After: 2, luego un 500, luego un 200 con un cuerpo válido. Un punto final, tres respuestas programadas, un arco de recuperación completo en una sola ejecución. - Dirige el agente al simulacro. Apunta la herramienta del agente a la URL del simulacro en lugar del servicio real y ejecuta el escenario de principio a fin.
- Afirma el comportamiento. Verifica lo que importa: el agente esperó al menos 2 segundos después del 429 antes de reintentar, reintentó después del 500, tuvo éxito en la tercera llamada y nunca excedió tu límite de intentos.
Ese escenario demuestra el retroceso y Retry-After en una sola pasada. Añade un segundo escenario para la ruta de abandono: programa el simulacro para que falle siempre y afirma que el agente se detiene en el límite y devuelve un error limpio en lugar de entrar en un bucle. Añade un tercero para el disyuntor: provoca suficientes fallos seguidos y afirma que el agente se activa y falla rápidamente en lugar de pagar un tiempo de espera en cada intento.
La verificación de idempotencia es la que la gente omite, y es la que ahorra dinero. Programa el simulacro para que acepte una llamada mutante, elimine la respuesta para que el agente piense que falló, y luego acepte el reintento. Ahora afirma la forma de la solicitud: ambas solicitudes llevaban la misma Idempotency-Key, y el simulacro vio una acción lógica, no dos. Una clave nueva en el reintento, o una llamada duplicada, significa que encontraste un doble envío antes de que lo hiciera un cliente. El método más amplio para probar agentes que llaman a tus APIs configura el arnés de extremo a extremo.
La lista de verificación de recuperación de errores
Antes de que un agente pase a producción, revisa esta lista:
- Cada llamada saliente tiene un tiempo de espera de conexión, un tiempo de espera de lectura y un presupuesto total de ejecución.
- Los reintentos utilizan retroceso exponencial con fluctuación, limitado tanto en el retraso como en el número de intentos.
- Las respuestas 429 leen y respetan
Retry-After, con retroceso como mecanismo de reserva. - Un disyuntor se activa por dependencia para que un servicio inactivo falle rápidamente en lugar de entrar en un bucle.
- Cada llamada que cambia de estado lleva una clave de idempotencia estable que sobrevive a los reintentos.
- La ruta de abandono devuelve un error limpio, no una espera infinita.
- Cada uno de estos se demuestra mediante una prueba que fuerza el fallo contra un simulacro, no se asume.
Marca las siete y tu agente se recuperará a propósito en lugar de por suerte.
Dónde encaja Apidog (y dónde no)
Mantén la honestidad del trabajo de la herramienta. Apidog no es un framework de agentes, un host de modelos o un entorno de ejecución. No construye, ejecuta ni orquesta tu agente, y no califica la salida del modelo. Lo que sí posee es la capa de API a la que llama tu agente, que es exactamente donde la recuperación se gana o se pierde.
Eso le da tres trabajos. Simula las dependencias a las que accede tu agente, para que obtengas un sustituto controlable en lugar del servicio en vivo. Programa las respuestas de fallo (429 con Retry-After, 500, tiempo de espera, cuerpo malformado) que una API real no producirá bajo demanda, para que puedas ensayar la recuperación. Y valida las solicitudes que recibe el simulacro (clave de idempotencia presente y estable, formato correcto, número de llamadas esperado) para que un doble envío o un encabezado omitido falle en una prueba en lugar de un cliente. Ese es el ajuste honesto: Apidog simula los fallos que tu agente debe sobrevivir y verifica lo que envía de vuelta.
Preguntas frecuentes
¿El SDK de Anthropic no maneja los reintentos por mí? Para sus propias llamadas, sí. El SDK reintenta ciertos errores con retroceso exponencial y respeta Retry-After, y tú estableces el límite con una opción de reintentos máximos. No cubre las otras APIs a las que llaman las herramientas de tu agente. Esas necesitan los mismos patrones aplicados por ti.
¿Cuándo necesito una clave de idempotencia? En cualquier llamada que cree o cambie el estado: cargos, pedidos, mensajes enviados, nuevos registros. Las llamadas de solo lectura son seguras de reintentar sin una. Genera la clave una vez por acción para que permanezca estable en los reintentos.
Ensaya un fallo esta semana
No tienes que construir los cuatro patrones a la vez. Elige el que más daño causaría, generalmente el bucle de límite de tasa o un reintento no idempotente, y ensáyalo contra un simulacro. Programa el 429, elimina una respuesta y observa lo que envía el agente. La primera vez que veas un retroceso limpio y una única clave de idempotencia donde temías un doble cargo, confiarás en el agente por una razón mejor que una demostración sin problemas.
Descarga Apidog para simular los fallos, programar la secuencia y verificar lo que hace tu agente cuando la API responde.