toklock: el proxy que encola requests de Claude sin 429

Si alguna vez corriste varios agentes de Claude en paralelo, sabés exactamente qué pasa: en algún momento el sistema explota con un error 429 y todo se frena. toklock es un proxy rate limit para la API de Claude que en vez de tirar el error lo encola, esperando que el presupuesto de tokens se recupere antes de reenviar la request. Lo construyó Tamil89 para su propio proyecto con 11 agentes autónomos corriendo en simultáneo, y lo publicó el 26 de mayo de 2026.

En 30 segundos

  • toklock es un proxy middleware que se sienta entre tus agentes y la API de Anthropic, eliminando los errores 429 por rate limit.
  • El SDK oficial de Anthropic solo reintenta 2 veces antes de lanzar la excepción. toklock encola la request indefinidamente hasta que hay presupuesto disponible.
  • Lee los headers de respuesta de Anthropic (anthropic-ratelimit-tokens-remaining y anthropic-ratelimit-tokens-reset) para saber exactamente cuándo liberar cada request encolada.
  • La configuración es una sola línea: export ANTHROPIC_BASE_URL=http://127.0.0.1:4000. Sin archivos de config, sin cambiar API keys.
  • Todas las soluciones alternativas existentes (Helicone, LiteLLM OSS, Portkey) o fallan ante 429 o cuestan cientos de dólares al mes.

El problema: Error 429 y los límites de velocidad de Anthropic

toklock es un proxy de rate limiting para la API de Anthropic que intercepta las requests de tus agentes, estima el costo en tokens antes de enviarlas, y las encola cuando el presupuesto está agotado. Los callers nunca reciben un error 429 — simplemente esperan.

Los rate limits de Anthropic tienen tres dimensiones: RPM (requests por minuto), ITPM (tokens de input por minuto) y OTPM (tokens de output por minuto). En el tier gratuito y los tiers bajos, el límite de tokens de input puede ser tan bajo como 30.000 por minuto. Para un solo agente que hace consultas simples, eso alcanza sin problema. Para once agentes ejecutándose en paralelo que disparan al mismo tiempo, es una muralla.

Ponele que estás corriendo un sistema de agentes para una SaaS: un agente analiza datos del usuario, otro genera recomendaciones, otro prepara reportes. Todos se disparan al mismo tiempo porque el usuario hace clic en “Procesar”. Con 30.000 tokens por minuto compartidos entre todos, el primero pasa, el segundo quizás pasa, y del tercero en adelante empieza el baile de los 429.

Por qué falla la SDK y las soluciones estándar

El SDK oficial de Anthropic tiene retry incorporado. Reintenta dos veces con exponential backoff y después lanza la excepción. Eso alcanza para errores transitorios de red, pero no para rate limits reales donde vas a seguir chocando hasta que el presupuesto de tokens se recupere.

¿Y qué pasó cuando buscaron soluciones alternativas? Exacto, tampoco funcionaban del todo. Helicone tiene retry acotado que igual termina fallando. LiteLLM en su versión open source devuelve el 429 directamente sin ningún manejo especial. La versión Enterprise de LiteLLM sí tiene queuing, pero el costo es prohibitivo para un proyecto en etapa inicial. Portkey hace load balancing entre múltiples providers, que es útil si tenés credenciales de varios proveedores, pero si solo tenés la API de Anthropic no te resuelve nada. Tema relacionado: en tus pipelines de CI/CD.

El problema con el simple retry con exponential backoff es matemático: si tenés N agentes todos esperando la misma ventana de tokens, cuando el presupuesto se recupera todos mandan su request al mismo tiempo y volvés a exceder el límite. Es un convoy que sigue chocando en la misma esquina cada vez que el semáforo cambia.

Introducción a toklock: el proxy que encola en lugar de fallar

Tamil89 lo construyó porque estaba desarrollando Visibrand, una SaaS de IA con 11 agentes autónomos de Claude corriendo en Railway. Cuando todos disparaban a la vez, el sistema se caía. Revisó cada herramienta existente y ninguna resolvía el problema con queuing real a costo razonable, así que lo construyó él mismo.

La propuesta es directa: toklock se para en el medio, entre tus agentes y api.anthropic.com, y maneja el presupuesto de tokens de forma centralizada. Todos los agentes hablan con toklock como si fuera Anthropic (mismo contrato de API, mismos endpoints). toklock habla con Anthropic real. Si hay presupuesto, la request pasa inmediatamente. Si no, espera exactamente hasta que lo haya.

Cómo funciona toklock internamente

El algoritmo tiene cinco pasos bien definidos según la publicación original del autor:

  • Todas las requests entran a una cola serial. No hay paralelismo en el envío.
  • Antes de enviar, toklock estima el costo en tokens mirando el cuerpo de la request.
  • Si el presupuesto restante es menor al costo estimado, la cola se pausa.
  • Lee el header anthropic-ratelimit-tokens-reset para saber exactamente cuándo se recupera el presupuesto, y espera ese tiempo exacto.
  • Reenvía la request a api.anthropic.com y actualiza el presupuesto con los conteos reales que vienen en los headers de respuesta.

Lo inteligente acá es que Anthropic incluye en cada respuesta los headers anthropic-ratelimit-tokens-remaining y anthropic-ratelimit-tokens-reset. No es un polling ni una estimación: toklock sabe exactamente cuántos tokens quedan y exactamente cuándo se refresca el límite. La espera no es aleatoria con jitter, es determinística. El agente B espera 47 segundos porque en exactamente 47 segundos va a haber presupuesto para su request.

Eso sí: la cola es serial, no concurrente. Todos los requests se procesan uno a la vez en orden. Para la mayoría de los casos de agentes esto no es problema porque cada agente espera su turno, pero si necesitás throughput máximo con presupuesto disponible es algo a considerar. Relacionado: como en tus flujos automatizados.

Instalación y configuración en 2 minutos

La configuración es una línea. Levantás toklock localmente y le decís al SDK de Anthropic que apunte ahí:

  • Levantás toklock en http://127.0.0.1:4000
  • Exportás ANTHROPIC_BASE_URL=http://127.0.0.1:4000
  • Corrés tu código normalmente (claude o cualquier llamada al SDK de Anthropic)

Sin archivos de configuración adicionales. Sin cambiar la API key. Sin modificar el código de los agentes. El SDK de Anthropic respeta la variable ANTHROPIC_BASE_URL por diseño, así que cualquier proyecto que use el SDK oficial funciona sin tocar una línea de código.

Para desplegar en producción junto a tus agentes (en Railway, en un VPS en donweb.com o donde tengas tu infraestructura), toklock corre como un servicio separado y los agentes apuntan a su dirección interna.

Comparativa: toklock vs otras soluciones de proxy rate limit Claude API

HerramientaQué hace ante 429Queuing realConfiguraciónCosto
SDK oficial AnthropicReintenta 2x, luego lanza excepciónNoNingunaGratis
HeliconeRetry acotado, igual puede fallarNoAPI key proxyFreemium
LiteLLM OSSDevuelve 429 directamenteNoArchivo YAMLGratis
LiteLLM EnterpriseEncolaSíCompleja$$$
PortkeyLoad balance entre providersNoAPI key proxyFreemium
toklockEncola con espera determinísticaSí1 variable de entornoOpen source

La columna que importa es “Queuing real”. Solo LiteLLM Enterprise y toklock la tienen. La diferencia es que LiteLLM Enterprise tiene un costo que no tiene sentido para un proyecto chico o para un equipo que recién arranca. (Y si ya estás pagando LiteLLM Enterprise por esto solo, probablemente estés pagando demasiado.)

Casos de uso: de agentes autónomos a SaaS multiusuario

El caso de Visibrand es el más obvio: múltiples agentes paralelos que comparten un presupuesto de tokens. Pero hay otros escenarios donde toklock tiene sentido.

Subís un batch de documentos para procesar, el sistema dispara 20 requests en 3 segundos, y sin gestión centralizada choca contra el límite, se cae, y tenés que manejar reintentos parciales con lógica de checkpointing. Con toklock, las 20 requests entran a la cola, se procesan en orden, y el sistema simplemente tarda más en lugar de fallar. Lo explicamos a fondo en comparado con otros proveedores.

En aplicaciones SaaS multiusuario donde varios usuarios hacen requests al mismo tiempo, el límite de tokens de Anthropic es compartido por toda tu organización. Un usuario que manda 10 requests grandes puede dejar sin presupuesto a todos los demás por el próximo minuto. toklock da una cola FIFO que distribuye el presupuesto entre todos sin que nadie reciba un error.

Errores comunes al manejar rate limits en la API de Anthropic

Error 1: Tratar el 429 como un error de red transitorio. El 429 de Anthropic no es que el servidor está ocupado. Es que vos específicamente agotaste tu presupuesto. Reintentar agresivamente no solo no ayuda: consume más tokens de la ventana siguiente y agrava el problema.

Error 2: Solo medir RPM e ignorar ITPM. Muchos implementan throttling mirando cuántas requests por minuto mandan, pero el límite que más duele en la práctica es el de tokens de input por minuto. Una sola request con un prompt largo puede consumir el presupuesto de 10 requests normales.

Error 3: Asumir que el presupuesto se recupera exactamente al minuto. Anthropic resetea el límite en intervalos que no siempre son 60 segundos exactos desde tu primera request. Por eso toklock lee el header anthropic-ratelimit-tokens-reset en lugar de implementar un timer propio. El header dice exactamente cuándo reintentrar.

Preguntas Frecuentes

¿Cómo soluciono el error 429 en la API de Claude?

El error 429 de Anthropic indica que agotaste el límite de tokens por minuto de tu organización. La solución inmediata es esperar al reset del límite (Anthropic lo informa en el header anthropic-ratelimit-tokens-reset). Para una solución estructural con múltiples agentes, un proxy como toklock encola las requests automáticamente en vez de lanzar el error. Te puede servir nuestra cobertura de frente a ejecutar agentes localmente.

¿Qué hace un proxy de rate limiting para la API de Anthropic?

Un proxy de rate limiting se interpone entre tu código y la API de Anthropic, interceptando todas las requests antes de enviarlas. Lleva un registro del presupuesto de tokens disponible y, cuando está agotado, retiene las requests en cola en lugar de enviarlas (y recibir un 429). Cuando el presupuesto se recupera, libera las requests en orden.

¿Cómo se instala y usa toklock con el SDK de Anthropic?

Levantás toklock localmente y configurás la variable de entorno ANTHROPIC_BASE_URL=http://127.0.0.1:4000. El SDK de Anthropic respeta esa variable y redirige todas las llamadas a toklock en lugar de ir directo a api.anthropic.com. No hay que cambiar API keys ni modificar el código de los agentes.

¿Cómo evitar que los agentes autónomos choquen contra los rate limits de Anthropic?

La causa raíz es que múltiples agentes comparten un presupuesto de tokens sin coordinación centralizada. Las opciones son: reducir la concurrencia manualmente (cada agente espera que el anterior termine), implementar un semáforo con token bucket en tu código, o usar un proxy centralizado como toklock que gestiona el presupuesto para todos los agentes de forma transparente.

¿Cuál es la diferencia entre toklock y LiteLLM para gestionar rate limits?

LiteLLM OSS no tiene queuing: devuelve el 429 directamente. LiteLLM Enterprise sí tiene queuing pero tiene un costo significativo pensado para empresas. toklock es open source, tiene queuing determinístico basado en los headers de Anthropic, y se configura con una variable de entorno. Para proyectos que solo usan la API de Anthropic y necesitan queuing sin costo adicional, toklock es la opción más directa disponible en 2026.

Conclusión

toklock resuelve un problema concreto que el SDK oficial no maneja bien: múltiples agentes compitiendo por el mismo presupuesto de tokens. La solución de encolado determinístico basado en headers de Anthropic es más robusta que cualquier implementación de retry con backoff, porque no adivina cuándo reintentar sino que sabe exactamente cuándo hay presupuesto disponible.

Si estás construyendo un sistema con más de dos o tres agentes paralelos usando la API de Claude, los 429 van a aparecer más temprano que tarde. Toklock no es la única solución, pero sí la más simple de implementar que tiene queuing real sin costo adicional. Vale la pena tenerlo en el radar antes de que los errores empiecen a aparecer en producción.

Fuentes

Te puede interesar...