Claude Usage Limits Agent: Arreglar cortes y límites

Hola, Lena está aquí. Hubo un momento el año pasado en que estaba mirando un flujo de trabajo que llevaba dos semanas funcionando bien, y de repente... se detuvo. Sin error útil. Sin razón obvia. La tarea estaba al 80% terminada y el agente se había quedado callado.

Pasé las siguientes horas pensando que era mi código. No lo era. Era un límite de uso de Claude — pero no el que pensaba que habría alcanzado.

Esa experiencia me hizo reflexionar. La mayoría de las soluciones de problemas que había visto trataban "Claude está caído" como un solo problema con una sola solución. Pero sentado con los registros, empecé a notar que tres cosas completamente diferentes se confundían entre sí. Y una vez que pude distinguirlas, las soluciones se hicieron mucho más evidentes.

Esta es esa crisis — la que ojalá hubiera tenido antes de empezar.

¿Qué pasa realmente cuando Claude alcanza un límite o cae

Lo primero que merece la pena ralentizar: no todos los fallos de Claude son del mismo tipo.

Límites de tarifa vs límites de uso vs cortes

Estos son tres problemas distintos con causas distintas, firmas de error distintas y soluciones distintas. Mezclarlos hace perder tiempo.

Los límites de tasa son las restricciones por minuto sobre solicitudes y tokens. Tu límite de tasa depende de tu nivel de uso y se mide en tres métricas clave: peticiones por minuto (RPM), tokens por minuto (TPM) y, a veces, cuotas diarias de tokens. Cuando superas estos, obtienes una 429 Too Many Requests HTTP. Esto es un problema de rendimiento: estás pidiendo demasiado, demasiado rápido, en una ventana corta.

Los límites de uso son diferentes. Los límites de tasa de Claude Code funcionan como un sistema de tres restricciones independientes y solapadas, y el porcentaje del panel refleja solo una de ellas. Podrías mirar tu consola Anthropic y ver un 6% de uso diario restante, asumir que todo está bien y aun así encontrarte con un muro — porque has superado el límite de tokens por minuto, no el diario. Es una distinción sutil pero importante.

Las interrupciones son otra categoría completamente distinta. Un 529 Service Unavailable significa que los servidores de Anthropic están estresados a nivel de sistema. El error 529 no es culpa tuya: ocurre cuando los servidores de Anthropic reciben mucho tráfico en todos los usuarios, y las solicitudes 529 rechazadas no cuentan para tu facturación. No puedes arreglar un 529 mediante optimización del código. Esperas, te echas atrás y revisas la página de estado de Anthropic para actualizaciones de incidentes.

La razón por la que esta distinción importa tanto: el diagnóstico incorrecto conduce a la solución incorrecta. He visto a personas actualizar su nivel de API tratando de arreglar lo que en realidad era una interrupción transitoria. Y he visto a otros esperar pacientemente a que un error 429 “se resolviera solo” cuando lo que realmente necesitaban era un patrón de solicitud diferente.

Cómo cada modo de falla afecta los flujos de trabajo del agente

Una interfaz de chat es bastante tolerante cuando Claude alcanza un límite. Ves un mensaje, esperas, lo intentas de nuevo.

Los flujos de trabajo del agente no son tolerantes. Claude Code no envía un solo prompt a la API y espera una respuesta: cada interacción es una conversación de varios turnos que incluye el prompt del sistema, el historial acumulado de la conversación, el contenido de los archivos incorporados al contexto y los tokens de uso de herramientas. Un comando aparentemente simple como “editar este archivo” podría consumir entre 50,000 y 150,000 tokens en una sola llamada a la API una vez que se ensambla todo el contexto.

Los límites de tasa en este entorno causan bucles de reintento: el agente sigue enviando solicitudes, cada una falla, cada una consume tokens que cuentan contra tu cuota. Alcanzar el límite de uso puede detener la ejecución a mitad de tarea, a veces sin una señal clara de que el problema fue el límite. Y las interrupciones causan lo que considero fallas silenciosas: la llamada a la herramienta se cuelga, se agota el tiempo y, dependiendo de tu configuración, puede que no registre nada útil.

Aquí es donde pasé unas horas incómodas con ese flujo de trabajo detenido. El agente había alcanzado un límite de tasa, entró en un bucle de reintento sin esperar, y consumió mi presupuesto de tokens restante antes de que me diera cuenta.

Soluciones inmediatas para cada modo de falla

Límites de tasa: detener la pérdida primero

La solución inmediata más efectiva es la espera exponencial con jitter. La idea: cada reintento espera el doble que el anterior, con un pequeño desplazamiento aleatorio (jitter) para distribuir los reintentos agrupados de múltiples clientes.

La parte del jitter es fácil de pasar por alto, pero importa. Sin él, cuando varios trabajadores o hilos de agentes paralelos alcanzan el mismo límite de tasa y luego todos reintentan exactamente al mismo intervalo, recreas el problema de ráfagas en cada ciclo de reintento. No estás resolviendo el problema: lo estás posponiendo con un desplazamiento fijo.

Un patrón simple en Python que me ha servido bien:

Python

import time, random
from anthropic import Anthropic, RateLimitError

def call_with_backoff(client, messages, max_retries=5):
    for attempt in range(max_retries):
        try:
            return client.messages.create(
                model="claude-sonnet-4-6",
                max_tokens=1024,
                messages=messages
            )
        except RateLimitError as e:
            if attempt == max_retries - 1:
                raise
            base_wait = min(2 ** attempt, 60)
            wait_time = base_wait + (random.random() * base_wait * 0.1)
            time.sleep(wait_time)

Vale la pena señalar: el SDK oficial de Python de Anthropic incluye lógica de reintento incorporada por defecto. Reintenta errores 429 hasta 2 veces con retroceso exponencial. Para flujos de trabajo de agentes en producción con mayores requisitos de tolerancia a fallos, normalmente querrás configurar eso con un valor más alto de max_retries y tu propia lógica de jitter.

Más allá de los reintentos, reduce el paralelismo. Si tienes cinco hilos de agentes haciendo llamadas a la API de Claude simultáneamente, y tu límite de velocidad es de 50RPM con un pool de tokens compartido, casi con seguridad vas a tener colisiones. Espacia las solicitudes, agrúpalas donde puedas, y no asumas que la ejecución en paralelo escala linealmente con el rendimiento.

Límites de uso: No reinicies desde cero

Un límite alcanzado a mitad de una tarea es uno de los modos de fallo más frustrantes porque el trabajo realizado antes de alcanzar el límite generalmente sigue siendo válido. La solución no es reiniciar, sino guardar el estado y reanudar.

Si estás en un plan de suscripción y alcanzas límites con frecuencia en flujos de trabajo en producción, la API Batch permite el procesamiento asincrónico de grandes volúmenes de solicitudes con un 50% de descuento tanto en tokens de entrada como de salida, lo que amplía significativamente tu capacidad efectiva para tareas que no requieren baja latencia. Vale la pena implementar el almacenamiento en caché de prompts si tienes prompts de sistema grandes o contexto repetido: los tokens en caché cuestan una fracción de los tokens de entrada estándar, y en sesiones largas de agentes donde se reenvía el mismo contexto repetidamente, esto se acumula rápidamente.

Si el límite de uso es una incompatibilidad estructural —realmente necesitas más rendimiento del que tu nivel actual proporciona— verifica los límites del plan actual en docs.anthropic.com/en/api/rate-limits antes de tomar decisiones sobre niveles, ya que estos números cambian sin previo aviso.

Manejo de interrupciones: degradar con gracia

Para interrupciones, los patrones principales son los interruptores automáticos (circuit breakers) y la degradación con gracia.

Los patrones de circuit breaker tienen tres estados: Cerrado (operación normal), Abierto (fallos detectados — dejar de intentar) y Medio-Abierto (probando si el servicio se ha recuperado). Aplicado a una integración con la API de Claude: después de N fallos consecutivos, el circuito se abre y deja de enviar solicitudes. Después de un período de espera, permite una única solicitud de prueba. Si esa tiene éxito, el circuito se cierra nuevamente.

La principal diferencia de comportamiento respecto a los reintentos: los reintentos manejan fallos individuales de solicitudes, los interruptores de circuito manejan fallos sistémicos. Si Claude está inactivo durante 20 minutos, no quieres que tu agente realice 400 llamadas fallidas a la API durante ese periodo. Quieres que detecte el patrón, deje de intentar, encole el trabajo y reanude cuando el servicio se recupere.

Construyendo Resiliencia en el Flujo de Trabajo de tu Agente

Estos patrones son donde está la parte interesante, al menos para mí. Las correcciones inmediatas anteriores detienen la hemorragia. Esta sección trata de no sangrar en primer lugar.

Enrutamiento de Modelo de Respaldo

Cuando Claude no está disponible, tener un endpoint de modelo de respaldo significa que tu agente puede continuar con capacidad reducida en lugar de detenerse por completo. La forma práctica de esto: tu flujo de trabajo principal se enruta a Claude; si obtienes un 529 o se dispara un interruptor de circuito, enrutas a un modelo secundario para tareas de menor importancia mientras se encola el trabajo crítico para que Claude lo reanude.

Esto no es algo simple de reemplazar: diferentes modelos tienen distintos comportamientos en llamadas a herramientas, formatos de contexto y consistencia de salida. Sugeriría comenzar con un alcance de respaldo reducido: identifica las partes del flujo de trabajo de tu agente que sean realmente agnósticas al modelo (resumen, clasificación simple, conversión de formato) y enruta esas primero a un respaldo. Mantén los pasos complejos y con herramientas en la cola.

Para enrutamiento multi-proveedor con lógica de respaldo adecuada, el gateway LLM de Portkey cubre los patrones en detalle: la combinación de reintentos, respaldos e interruptores de circuito como un sistema por capas vale la pena leerla si estás construyendo para confiabilidad en producción.

Patrones de Punto de Control y Reanudación

Esta parte aún no la he resuelto completamente, si soy honesto. Pero la dirección es clara: el estado del agente necesita ser serializable en los límites de la tarea.

La forma básica: antes de una llamada a la API de Claude, serializa el estado actual de tu agente — progreso de la tarea, pasos completados, resultados intermedios — a almacenamiento persistente. Si la llamada falla y se dispara el interruptor de circuito, tienes un punto de control desde el cual reanudar en lugar de empezar de nuevo.

La parte más difícil es definir los "límites de la tarea" en flujos de trabajo de agente donde los pasos son interdependientes. He encontrado que el enfoque más limpio es tratar cada llamada a una herramienta como un posible punto de control, incluso si parece granular. Es más fácil fusionar puntos de control que desenredar una tarea multi-paso parcialmente completada sin un punto de recuperación.

Separando la Ruta Crítica de las Tareas en Segundo Plano

No todas las tareas del agente necesitan las mismas garantías de disponibilidad. Las tareas en segundo plano — registro, resumen, análisis de baja prioridad — pueden tolerar que Claude no esté disponible durante minutos u horas. Las tareas críticas no pueden.

Modelar esto explícitamente te permite diseñar diferentes perfiles de resistencia: la ruta crítica recibe una lógica de reintento agresiva, modelos de respaldo y monitoreo de disyuntores; las tareas en segundo plano se ponen en cola con paciencia y sin presión de reintento. Esto por sí solo reduce significativamente el ruido de los límites de uso de Claude, porque ya no estás tratando cada llamada fallida a la API como igualmente urgente.

El problema más profundo: cada solución alternativa se redescubre

Esto es lo que me ha estado molestando en todo este ámbito.

He hablado con suficientes personas que construyen flujos de trabajo basados en Claude como para notar un patrón. Alguien resuelve el problema del retroceso exponencial. Lo implementa bien. Funciona. Luego, tres meses después, un compañero de equipo inicia un nuevo proyecto, tiene los mismos errores 429 y lo resuelve de nuevo — ligeramente diferente, en un archivo ligeramente diferente, de una manera ligeramente diferente. La primera solución nunca se transfirió.

Lo mismo aplica a patrones de puntos de control, configuraciones de disyuntores, lógica de enrutamiento de respaldo. Un contador global de reintentos trata todas las herramientas como un único dominio de fallas — cuando una herramienta se degrada, agota el presupuesto para todas las demás herramientas. Alguien descubre esto, construye disyuntores por herramienta, y vive en el código de un proyecto, sin documentación, sin ser referenciado por el próximo proyecto que se enfrenta al mismo problema.

Esto no es un problema de código, es un problema de estructura de conocimiento. Una estrategia de respaldo validada pertenece a una forma reutilizable que viaje con la capacidad del agente, no en un registro de chat o en un script único que se olvida.

No tengo una respuesta completa a esto. Sigo pensando en ello.

Preguntas frecuentes

¿Cuáles son los límites de tasa actuales de Claude para usuarios de API?

Estos cambian, así que verifica la documentación oficial de límites de tasa de Anthropic antes de tomar decisiones arquitectónicas. Como referencia aproximada: los límites se basan en niveles (Nivel 1 al 4), medidos en RPM, ITPM y OTPM, con niveles superiores desbloqueados tras alcanzar umbrales de gasto. El Nivel 1 comienza con límites conservadores; el Nivel 4 es significativamente más generoso. Los números de artículos de 2025 probablemente ya estén desactualizados.

¿Cómo manejo las interrupciones de Claude en un flujo de trabajo de agente en producción?

Los disyuntores son el patrón correcto. Abra el circuito después de un umbral de fallos consecutivos, ponga en cola el trabajo durante el estado abierto, haga una prueba después de un tiempo de espera, cierre cuando el servicio se recupere. Verifique status.anthropic.com en su monitoreo para distinguir un problema localizado de un incidente a nivel de plataforma.

¿Cuál es el mejor modelo de respaldo cuando Claude no está disponible?

No hay una respuesta universal aquí: depende de lo que esté haciendo su agente. Para tareas de salida estructurada, la mayoría de los modelos capaces lo manejan razonablemente bien. Para cadenas complejas de uso de herramientas y razonamiento de múltiples pasos, la calidad del respaldo disminuye de manera más notable. Comience identificando la porción estrecha de su flujo de trabajo que es genuinamente independiente del modelo y dirija eso primero a un respaldo.

¿Cómo puedo guardar el estado del agente para que un fallo de Claude no reinicie mi tarea desde cero?

Serialice el estado del agente en los límites de la tarea antes de cada llamada a la API de Claude. Como mínimo: pasos completados, salidas intermedias, posición actual en el grafo de tareas. La pregunta sobre la granularidad es más complicada: tienda hacia puntos de control más frecuentes. El almacenamiento es barato; volver a ejecutar una tarea de agente de dos horas no lo es.

¿Cómo evito que mi agente consuma tokens en reintentos fallidos?

Dos cosas: retroceso exponencial con fluctuación (jitter) para que los reintentos no generen ráfagas sincronizadas, y disyuntores (circuit breakers) para que las fallas sistémicas no sigan consumiendo el presupuesto de reintentos. El SDK de Python de Anthropic tiene lógica básica de reintentos incorporada: configúrelo explícitamente en lugar de depender de los valores predeterminados. Para sistemas de producción con paralelismo, agregue disyuntores por herramienta o por operación para que un punto final degradado no agote todo su presupuesto de reintentos.

Probablemente seguiré observando cómo evoluciona esto. Los patrones de límite y resiliencia parecen aún estar en desarrollo público, y no estoy seguro de haber llegado al fondo de cómo se ve la versión más limpia para flujos de trabajo agenticos de larga duración. Pero la distinción entre los tres modos de fallo, al menos, se siente más definida.