Límite de solicitudes de una API de agentes de IA: reintentos seguros

Un agente que alcanza una cuota debe reducir la velocidad, contabilizar cada intento adicional y detenerse antes de convertir un rechazo temporal en un problema operativo mayor. «Reintentar si falla» puede ser un consejo suficiente para una persona que pulsa un botón. Es un consejo peligroso para un proceso capaz de emitir solicitudes más rápido de lo que cualquiera puede supervisar.

La dificultad no está en esperar unos segundos. Está en conservar el significado de la tarea original cuando la primera solicitud pudo fallar antes de llegar al proveedor, después de que el proveedor la completara o porque varias ejecuciones del agente agotaron una misma cuota compartida. Un diseño seguro separa esos casos y convierte la intervención humana en un resultado definido, no en una excepción incómoda.

Un 429 es una instrucción de planificación, no un error que deba golpearse

HTTP 429 significa que el servidor rechaza la solicitud porque el cliente envió demasiadas solicitudes durante un periodo que controla el servidor. RFC 6585 define el código de estado y señala que la representación de la respuesta debe explicar la condición y puede incluir un encabezado Retry-After. La formulación importa: un 429 no indica al agente que repetir inmediatamente la misma solicitud tenga posibilidades de funcionar.

El agente debe registrar primero el proveedor, el endpoint, la identidad de la credencial o de la cuenta, la clase de solicitud, el estado de la respuesta y los encabezados de límite. Después debe poner el trabajo en un estado retrasado. No dejes que el modelo de lenguaje decida esto en prosa después de cada fallo. La capa de transporte necesita un comportamiento determinista, porque un modelo bajo presión puede intentar otro endpoint cercano, cambiar un filtro o crear una segunda ruta de solicitud. Esas improvisaciones pueden multiplicar las llamadas y producir el mismo rechazo.

Un rechazo suele aplicarse a un grupo más amplio que la solicitud actual. Los proveedores suelen establecer límites por cuenta, proyecto, token, dirección IP, familia de endpoints o una combinación de ellos. Un agente puede recibir un 429 mientras otro, con la misma credencial, sigue funcionando durante un breve periodo. Eso no demuestra que el primero pueda reintentar sin riesgo. Puede significar que el proveedor tiene varios grupos o que el segundo proceso está consumiendo la capacidad restante.

Mantén un registro local para cada ámbito conocido. Si el servicio documenta un límite por token, agrupa las solicitudes por token. Si solo ofrece indicaciones a nivel de cuenta, supone que todos los trabajadores de esa cuenta comparten el grupo hasta que las pruebas indiquen lo contrario. Un registro local no reflejará perfectamente el contador interno del proveedor, pero evita que tus propios trabajadores compitan a ciegas.

La especificación de campos RateLimit del IETF, RFC 9333, define RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset. Estos campos describen el estado de la cuota, pero no borran un 429 ya recibido. Úsalos para regular las solicitudes futuras y evitar que la cola crezca más rápido de lo que el proveedor puede aceptar. Interpreta su ámbito según la documentación del proveedor, porque un encabezado por sí solo quizá no revele si se aplica a un endpoint o a una cuenta completa.

Un registro de estado útil puede tener este aspecto:

{
  "provider": "billing-api",
  "scope": "account:ops-team",
  "request_class": "write:invoice",
  "next_allowed_at": "2025-04-08T14:12:31Z",
  "remaining": 0,
  "reset_after_seconds": 60,
  "source": "HTTP 429 Retry-After"
}

El ejecutor del agente debe leer este registro antes de enviar otra llamada. Dormir dentro de un único gestor de solicitudes puede ser aceptable en una ejecución pequeña desde la línea de comandos. Una cola con un next_allowed_at visible es mejor cuando existen varios trabajadores, herramientas o tareas reanudadas. Permite que el planificador elija otro trabajo en lugar de mantener ocupado un proceso y ofrece al operador una explicación clara del retraso.

Los presupuestos de reintentos evitan que un fallo pequeño se convierta en una avalancha

Un presupuesto de reintentos establece un límite estricto para el trabajo adicional que una tarea puede generar después de una llamada fallida. Cuenta tanto los intentos como el tiempo de espera transcurrido. Un número fijo por sí solo falla cuando el servicio pide esperar minutos; un límite de tiempo por sí solo falla cuando un bucle rápido de reintentos consume la cuota de una cuenta en segundos.

Usa presupuestos separados para cada tarea y para cada ámbito compartido del proveedor. El presupuesto de una tarea responde a «¿cuánta incertidumbre puede tolerar este objetivo?». El presupuesto del ámbito responde a «¿cuánta alteración pueden causar todas las tareas actuales a este proveedor?». Si diez tareas reciben tres reintentos cada una, la cuenta puede recibir treinta solicitudes adicionales. Así es como una política supuestamente prudente se convierte en una ráfaga.

Para las lecturas habituales, uso un presupuesto pequeño y un plazo más corto que el valor empresarial de la respuesta. Para las escrituras, gasto mucho menos presupuesto en reintentos a ciegas. Esperar a una persona puede costar menos que duplicar un pago, enviar avisos repetidos o aplicar dos veces un despliegue.

Expresa la regla como datos que el agente no pueda cambiar a la ligera:

request_classes:
  read:
    max_attempts: 4
    max_wait_seconds: 90
    retry_statuses: [408, 429, 500, 502, 503, 504]
  idempotent_write:
    max_attempts: 3
    max_wait_seconds: 120
    retry_statuses: [408, 429, 502, 503, 504]
  uncertain_write:
    max_attempts: 1
    max_wait_seconds: 0
    retry_statuses: []
shared_scope:
  max_delayed_requests: 25
  max_concurrent_requests: 2

Este fragmento evita un fallo conocido: el agente recibe un tiempo de espera después de enviar una escritura, supone que no ocurrió nada y reintenta contra un proveedor que ya está bajo presión. La clase uncertain_write obliga a comprobar el estado o escalar el caso. No premia al agente por insistir cuando insistir cambia el resultado.

El presupuesto debe contabilizar cada intento real, incluidos los reintentos iniciados por las bibliotecas. He visto controles de reintentos declarados en una aplicación mientras un cliente HTTP, un ejecutor de flujos y un proxy reintentaban por debajo. El número final de solicitudes parecía inexplicable hasta que alguien revisó las tres configuraciones predeterminadas. Elige una capa responsable de los reintentos. Configura las demás para informar de los errores sin reintentar, o haz explícito su comportamiento e inclúyelo en el presupuesto total.

Agotar el presupuesto debe producir un resultado terminal con contexto, no un fallo genérico. El resultado debe indicar si la solicitud original se envió, si llegó una respuesta, cuántos intentos se hicieron, cuánto esperó la tarea y cuál es la siguiente acción segura. El agente podrá continuar con trabajo no relacionado o presentar una escalación precisa, en lugar de pedirse otra vez que «lo intente de nuevo».

El backoff necesita jitter y un límite

El backoff exponencial reduce la presión después de rechazos repetidos al aumentar el intervalo entre intentos. El jitter evita que muchos trabajadores que fallaron al mismo tiempo regresen en una ola sincronizada. Ambos deben estar en el cliente, aunque el proveedor publique una hora de restablecimiento, porque la concurrencia interna puede crear su propia avalancha.

Para el intento n, donde el primer reintento es n = 1, calcula un máximo y elige un retraso aleatorio dentro de ese límite:

import random

BASE_SECONDS = 1.0
MAX_SECONDS = 60.0

def retry_delay(attempt_number: int) -> float:
    cap = min(MAX_SECONDS, BASE_SECONDS * (2 ** attempt_number))
    return random.uniform(0, cap)

Esto es jitter completo. Evita que todos los trabajadores esperen exactamente 2, 4, 8 y 16 segundos. Los retrasos fijos iguales son populares porque facilitan la lectura de los registros. También hacen que los reintentos coordinados sean fáciles de predecir, justo lo contrario de lo que necesita un servicio ocupado.

Cuando una respuesta incluye Retry-After, ese valor tiene prioridad sobre un retraso local más corto. RFC 9110 permite que Retry-After sea un retraso en segundos o una fecha HTTP. Analiza ambos formatos. Si la fecha ya pasó porque el reloj de la máquina difiere del del proveedor, aplica un retraso mínimo moderado en lugar de entrar en un bucle de reintentos rápidos.

No uses el backoff como sustituto de la regulación de velocidad. El backoff empieza después de un fallo. Un token bucket, un leaky bucket o un límite sencillo del planificador controla la velocidad antes del fallo. Si un proveedor permite un número conocido de solicitudes durante un intervalo conocido, envíalas por debajo de esa cuota publicada y reserva capacidad para el trabajo interactivo. El planificador también debe limitar la concurrencia. Veinte solicitudes simultáneas pueden consumir la capacidad de un intervalo corto antes de que cualquier trabajador lea una respuesta RateLimit-Remaining.

Una regla práctica de envío es sencilla: antes de mandar una llamada, comprueba la hora de la siguiente solicitud permitida para el ámbito compartido y si hay un espacio de concurrencia disponible. Después de un 429, actualiza el registro del ámbito antes de programar cualquier reintento. El orden importa. Si los trabajadores programan sus reintentos antes de publicar el rechazo, cada uno puede concluir que le corresponde el siguiente espacio.

Pon un límite al retraso y al tiempo total de espera. Una curva exponencial sin límite puede aplazar una tarea durante horas y dejar activa una ejecución obsoleta mucho después de que caduquen sus supuestos. El agente debe fallar la tarea o entregarla al planificador después de su plazo, conservando la entrada original para revisarla más tarde.

La idempotencia decide si un reintento es seguro

Una solicitud idempotente produce el mismo efecto previsto cuando se repite. Eso no significa que toda solicitud que use HTTP PUT sea inofensiva en cualquier aplicación, ni que todo POST sea peligroso. RFC 9110 describe métodos como PUT y DELETE como idempotentes por intención, mientras que POST no suele ser idempotente. El contrato real de la API del proveedor determina el riesgo operativo.

Las solicitudes de lectura suelen tolerar reintentos, siempre que el agente acepte que los datos devueltos pueden haber cambiado. Una solicitud de borrado también puede tolerar un reintento si eliminar un recurso que ya no existe produce un resultado conocido y aceptable. Crear un pago, una invitación, un ticket de soporte, una orden de compra o un despliegue suele ser incompatible con la repetición a ciegas. Estas son las llamadas que requieren mayor cautela después de un tiempo de espera o un reinicio de conexión.

El sector suele confundir dos estados distintos:

• Una solicitud que con seguridad no llegó al proveedor se puede reenviar si la operación lo permite.
• Una solicitud cuyo resultado se desconoce necesita una conciliación antes de que el agente envíe otro efecto externo.

Un fallo de conexión después de que el cliente escriba los bytes no demuestra que el proveedor no haya actuado. El servidor podría haber completado la operación y perder la conexión de respuesta. El agente no puede deducir el resultado a partir de la ausencia de una respuesta.

Cuando un proveedor admite una clave de idempotencia, genera un token estable por cada acción lógica y reutilízalo en todos los reintentos de esa acción. No generes un token nuevo en cada intento. Un token nuevo indica al proveedor que cada reintento es una operación distinta, anulando la protección.

POST /v1/transfers HTTP/1.1
Idempotency-Key: transfer-7c41b5b9-7f5b-4f51
Content-Type: application/json

{"source":"acct_17","destination":"acct_42","amount":12500,"currency":"USD"}

Guarda el token junto con la tarea y la carga útil de la solicitud antes de enviar la primera llamada. Si el ejecutor se reinicia, debe recuperar el mismo token. Guarda también el identificador de operación devuelto por el proveedor. Ese identificador permite que una consulta de conciliación posterior pregunte por la acción original sin recrearla.

Si la API no ofrece idempotencia, busca un patrón de creación y consulta. El agente puede incluir una referencia externa generada por el cliente en la carga útil y después buscar esa referencia tras un fallo incierto. Si la API no ofrece idempotencia ni una búsqueda fiable, no automatices escrituras repetidas. Pide a una persona que revise los registros del proveedor. Parece más lento hasta que el primer efecto duplicado llega a un sistema que no puede deshacerlo limpiamente.

Separa los límites de solicitudes de las interrupciones y las solicitudes incorrectas

Una política que trata todos los estados que no indican éxito de la misma manera ocultará defectos y desperdiciará cuota. Clasifica la respuesta antes de elegir un retraso. Importan el código de estado, el cuerpo de la respuesta, el código de error del proveedor y el método de la solicitud.

Usa esta separación práctica:

• 429 significa reducir la velocidad, respetar las indicaciones del proveedor y descontar el intento del presupuesto compartido de límites.
• 408, los reinicios de conexión y algunas respuestas 5xx pueden justificar un reintento limitado, pero las operaciones de escritura siguen necesitando una ruta de idempotencia o conciliación.
• 400, 401, 403, 404 y 422 suelen requerir una solicitud corregida, un cambio de autorización o una decisión humana. Repetirlas es inútil.
• 409 requiere un tratamiento específico del recurso. Puede indicar un duplicado, un conflicto de versión o un bloqueo mantenido por otro flujo.
• Un error específico del proveedor por agotamiento de cuota puede exigir esperar hasta un restablecimiento de facturación o diario, algo distinto de un límite de ráfaga breve.

No trates 503 Service Unavailable como una forma intercambiable de 429. Un 503 indica que el servicio no puede atender la solicitud en ese momento; un 429 indica que el cliente superó un límite. Ambos pueden incluir Retry-After, pero un 429 debe hacer que el planificador reduzca la velocidad local para el ámbito afectado. Un 503 puede ser regional, específico de un endpoint o general del proveedor. Conserva la diferencia en las métricas y en los mensajes para operadores.

El comportamiento del agente también puede provocar oleadas de solicitudes inválidas. Un modelo puede llamar repetidamente a un endpoint con un filtro no compatible después de recibir 422, o reintentar 401 después de que se revoque la credencial. Coloca un interruptor de circuito alrededor de los fallos idénticos repetidos. Por ejemplo, si el mismo endpoint, método y código de error normalizado fallan varias veces en una ejecución, detén esa ruta y devuelve los detalles del error al agente como una restricción. No permitas que cambie espacios, reordene campos JSON y finja que está probando opciones nuevas.

Una huella normalizada de la solicitud debe excluir secretos y encabezados variables. Incluye el método, la plantilla del endpoint, los campos estables de la carga útil y el código de error de la API. Así el ejecutor puede detectar un bucle sin registrar credenciales ni cuerpos sensibles completos.

Las credenciales compartidas necesitan una cola, no agentes bienintencionados

Una credencial de API compartida crea un problema de coordinación que los agentes individuales no pueden resolver por sí solos. Cada proceso solo ve sus propias solicitudes, a menos que un planificador les proporcione un presupuesto común. El backoff por agente reduce la posibilidad de una ráfaga, pero no distribuye de manera justa una cuota escasa de toda la cuenta.

Coloca una cola de salida delante del ámbito de la credencial compartida. Asigna las prioridades de forma deliberada. Un cambio de producción aprobado por una persona puede tener prioridad sobre el trabajo de inventario en segundo plano. Un agente de larga duración que descubre diez mil registros debe recorrerlos al ritmo que permita el proveedor, en lugar de llenar la cola con todas las páginas a la vez.

La cola necesita cancelación. Si termina la tarea principal de un agente, descarta sus solicitudes retrasadas antes de que se reactiven. De lo contrario, una tarea detenida puede seguir consumiendo cuota más tarde y confundir el registro de auditoría. La cancelación también debe liberar cualquier espacio de concurrencia reservado.

Usa una regla de consolidación para lecturas seguras. Si cinco ejecuciones de agentes solicitan el mismo registro inmutable durante un intervalo breve, realiza una sola solicitud y distribuye el resultado entre las tareas que esperan. No consolides lecturas en las que la actualidad cambie el significado, como un saldo o un estado de aprobación. El objetivo es eliminar duplicados accidentales, no crear una caché que devuelva datos obsoletos a un agente que toma decisiones.

Los límites de solicitudes suelen revelar un problema de planificación más profundo. Un agente que llama a un endpoint de detalle una vez por elemento puede estar siguiendo exactamente sus instrucciones y, aun así, utilizar el patrón de acceso equivocado. Antes de añadir reintentos, busca endpoints por lotes, controles de paginación, solicitudes condicionales, webhooks, trabajos de exportación o un endpoint de búsqueda en el servidor. Estos cambios reducen las llamadas antes de que el proveedor tenga que rechazarlas.

Sallyport puede mantener las credenciales de API fuera del proceso del agente y registrar las llamadas salientes individuales, pero el emisor sigue necesitando controles de cola y reintentos. Separar las credenciales reduce la exposición de secretos; no cambia la cuota del proveedor.

La escalación humana debe conservar la incertidumbre

Una persona debe hacerse cargo cuando el sistema no pueda establecer si se produjo un efecto externo, cuando la espera restante supere el plazo de la tarea, cuando se agote la cuota compartida o cuando los límites repetidos apunten a un problema de configuración de la cuenta. Escalar no consiste en enviar una notificación genérica de «fallo de API». Es un expediente compacto que permite decidir sin reconstruir la ejecución a partir de registros dispersos.

Envía al operador estos datos:

• el resultado solicitado por la tarea y la acción lógica exacta que se detuvo;
• el proveedor, endpoint, método, ámbito de la cuenta y huella anonimizada de la solicitud;
• las marcas de tiempo de los intentos, los estados, los encabezados Retry-After o de límites y el presupuesto consumido;
• si la operación tiene un token de idempotencia, un identificador de operación del proveedor o una consulta de conciliación;
• las opciones seguras siguientes, como esperar, consultar el estado, aumentar la cuota, cambiar el plan o cancelar.

No incluyas por defecto el cuerpo de la solicitud sin filtrar en una tarjeta de aprobación. Puede contener datos personales, documentos internos o un valor que parezca inofensivo hasta llegar a la persona equivocada. Muestra un resumen conciso y convierte el acceso detallado en una acción de auditoría deliberada.

La aprobación debe pedir una decisión, no solo consentimiento para «continuar». Para una escritura incierta, ofrece «consultar la operación existente», «reintentar con el mismo token de idempotencia», «cancelar» y, cuando esté justificado, «enviar una operación nueva». La última opción debe indicar claramente que puede crear un segundo efecto externo. Las personas deciden mejor cuando las opciones describen el riesgo real.

La aprobación para mantener el acceso y la aprobación de una acción externa concreta son controles distintos. Una sesión puede seguir autorizada mientras el agente necesite una revisión por llamada para un pago, una escritura de producción o una solicitud repetida después de un evento de límite. Mantén esas decisiones separadas tanto en la interfaz como en el registro.

Al revisar una escalación, empieza por la conciliación. Consulta al proveedor mediante la clave de idempotencia, la referencia externa o el identificador de operación. Reintenta solo después de que la consulta muestre que no se completó ninguna acción o de que el proveedor garantice la supresión de duplicados. Este orden es más lento que reenviar a ciegas por un viaje de red, pero más rápido que reparar un duplicado que entró en un libro contable posterior.

Los registros de auditoría deben explicar la acción intentada y la espera

Un registro de auditoría útil responde a algo más que «¿la solicitud devolvió 200?». Debe mostrar qué intentó el agente, qué autorización lo permitió, qué devolvió el servicio remoto y cómo reaccionó el controlador de reintentos. Sin el registro de decisiones, una secuencia de llamadas puede parecer una repetición descuidada aunque el planificador haya obedecido un valor documentado de Retry-After.

Registra un evento antes del envío y añade después los eventos de resultado y planificación. Mantén los metadatos de la solicitud libres de credenciales en texto plano. Una secuencia compacta podría ser:

14:11:02 action_requested  task=sync-482 method=POST route=/records
14:11:02 action_sent       attempt=1 idempotency=rec-91f2
14:11:03 action_result     status=429 retry_after=30 scope=account:ops
14:11:03 retry_scheduled   attempt=2 due=14:11:33 budget_wait=30
14:11:33 action_sent       attempt=2 idempotency=rec-91f2
14:11:34 action_result     status=201 provider_id=r_893

Esa secuencia separa una acción lógica de sus intentos de transporte. Si alguien pregunta por qué se produjeron dos llamadas POST, el registro muestra que compartían un token de idempotencia y respetaban un retraso indicado por el proveedor. Si la segunda respuesta hubiera agotado el tiempo de espera, el siguiente evento debería ser reconciliation_required, no otro action_sent automático.

El registro a prueba de manipulaciones ofrece una ventaja práctica durante la revisión de incidentes: permite comprobar que una ejecución no borró después los intentos incómodos. Sallyport proyecta sus diarios de sesión y llamadas desde un registro de auditoría cifrado y encadenado mediante hash, y sp audit verify comprueba la cadena sin conexión, sin necesidad de una clave del almacén. Resulta útil cuando un operador necesita distinguir una limitación del proveedor de un bucle del agente o de un reintento manual tardío.

Los registros también necesitan límites de conservación y de acceso. Una ruta de solicitud, el identificador de una cuenta del proveedor y un patrón temporal pueden revelar actividad operativa sensible aunque el token nunca aparezca. Captura lo suficiente para reconstruir la decisión y limita quién puede buscar y exportar el registro.

Prueba las rutas de fallo antes de que un agente las descubra en producción

Un diseño de límites no está completo hasta que una prueba demuestra que detiene las llamadas, conserva la idempotencia y escala la incertidumbre. Simular un único 429 no basta. Necesitas trabajadores simultáneos y fallos que se produzcan después de que el servicio remoto pueda haber actuado.

Ejecuta esta secuencia en un entorno de pruebas o contra una API simulada controlable:

1. Inicia tres tareas de agentes que utilicen un único ámbito de cuenta simulado y emitan la misma solicitud de lectura segura.
2. Devuelve 429 con Retry-After: 10 a la primera solicitud y verifica que el planificador retrase todo el trabajo de ese ámbito, en lugar de dejar que los otros dos continúen a toda velocidad.
3. Devuelve éxito después del retraso y comprueba que los tiempos de reintento difieran ligeramente, en vez de llegar como una sola ráfaga.
4. Envía una escritura con un token de idempotencia estable, simula una caída de conexión después de que la API falsa guarde el registro y verifica que el ejecutor consulte el estado en lugar de emitir una nueva creación.
5. Agota el presupuesto de tiempo configurado y verifica que el operador reciba el registro de escalación anonimizado y que el trabajo cancelado no vuelva a despertarse más tarde.

Mide los intentos salientes en la API falsa, no solo las llamadas a funciones dentro del agente. Los contadores internos no detectan los reintentos añadidos por bibliotecas HTTP o envoltorios. Prueba también un reinicio: detén el ejecutor después de la primera escritura incierta, restaura su estado persistido y confirma que reanuda la conciliación con el token de idempotencia original.

No premies al banco de pruebas del agente por conseguir finalmente una respuesta correcta. Prémialo por hacer el número adecuado de llamadas, esperar cuando se le indique y dejar sin resolver una escritura ambigua hasta obtener pruebas. Un agente que «termina el trabajo» duplicando acciones externas no ha superado la prueba.

El primer control que debes implementar es un presupuesto compartido de reintentos con resultados terminales explícitos. Convierte la limitación de solicitudes de una invitación a seguir intentando en una decisión operativa con un registro, un plazo y una persona que pueda intervenir cuando el estado remoto sea incierto.