Limites de Uso do Agente Claude: Corrigir Interrupções e Limites

Olá, Lena aqui. Houve um momento no ano passado em que eu estava olhando para um fluxo de trabalho que estava funcionando bem há duas semanas, e então, de repente, ele simplesmente… parou. Sem erro útil. Sem razão óbvia. A tarefa estava 80% concluída, e o agente ficou silencioso.

Passei as próximas horas assumindo que o problema era meu código. Não era. Era um limite de uso do Claude — mas não o que eu pensei que tivesse atingido.

Essa experiência me fez refletir. A maior parte da solução de problemas que eu tinha visto tratava “Claude está fora do ar” como um único problema com uma única solução. Mas ao analisar os logs, comecei a notar que três coisas completamente diferentes estavam sendo confundidas umas com as outras. E uma vez que consegui distingui-las, as soluções ficaram muito mais óbvias.

Esta é a análise — aquela que eu gostaria de ter tido antes de começar.

O Que Realmente Acontece Quando o Claude Atinge um Limite ou Entra em Falha

A primeira coisa que vale a pena desacelerar: nem todas as falhas do Claude são do mesmo tipo de falha.

Limites de Taxa vs Limites de Uso vs Interrupções

Estes são três problemas distintos com causas diferentes, assinaturas de erro diferentes e soluções diferentes. Confundi-los faz você perder tempo.

Limites de taxa são as restrições por minuto em solicitações e tokens. Seu limite de taxa depende do seu nível de uso e é medido por três métricas principais: solicitações por minuto (RPM), tokens por minuto (TPM) e, às vezes, cotas diárias de tokens. Quando você excede esses limites, recebe um HTTP 429 Too Many Requests. Este é um problema de throughput — você está pedindo demais, rápido demais, dentro de uma janela curta.

Limites de uso são diferentes. Os limites de taxa do Claude Code operam como um sistema de três restrições independentes e sobrepostas, e a porcentagem exibida no painel reflete apenas uma delas. Você pode olhar para o console da Anthropic e ver 6% do uso diário restante, assumir que está tudo certo, e ainda assim atingir um limite — porque você já consumiu o teto de tokens por minuto, não o diário. É uma distinção sutil, mas importante.

Interrupções são uma categoria totalmente diferente. Um 529 Service Unavailable significa que os servidores da Anthropic estão sobrecarregados a nível de sistema. O erro 529 não é sua culpa — ele ocorre quando os servidores da Anthropic experimentam alto tráfego de todos os usuários, e as solicitações 529 rejeitadas não são contabilizadas na sua cobrança. Você não consegue corrigir um 529 com otimização de código. Você espera, recua e verifica a página de status da Anthropic para atualizações sobre incidentes.

A razão pela qual essa distinção importa tanto: um diagnóstico errado leva à solução errada. Eu já vi pessoas atualizando seu nível de API tentando corrigir algo que na verdade era uma interrupção temporária. E já vi outros esperando pacientemente por um 429 se “resolver sozinho”, quando o que eles realmente precisavam era de um padrão de requisição diferente.

Como Cada Modo de Falha Afeta os Fluxos de Trabalho do Agente

Uma interface de chat é bastante tolerante quando Claude atinge um limite. Você vê uma mensagem, espera e tenta novamente.

Os fluxos de trabalho dos agentes não são tolerantes. Claude Code não envia uma única instrução à API e espera por uma resposta — cada interação é uma conversa de várias etapas que inclui a instrução do sistema, o histórico acumulado da conversa, conteúdos de arquivos inseridos no contexto e tokens de uso de ferramentas. Um comando aparentemente simples como “edite este arquivo” pode consumir de 50.000 a 150.000 tokens em uma única chamada de API, uma vez que todo o contexto esteja montado.

Atingir limites de taxa nesse ambiente causa loops de tentativa — o agente continua enviando requisições, cada uma falhando, cada uma consumindo tokens que contam contra sua cota. Atingir o limite de uso pode interromper a execução no meio da tarefa, às vezes sem um sinal claro de que foi um problema de cota. E interrupções causam o que eu considero falhas silenciosas: a chamada de ferramenta trava, expira, e dependendo de como sua configuração está, pode não registrar nada útil.

Foi aqui que passei algumas horas desconfortáveis com aquele fluxo de trabalho travado. O agente atingiu um limite de taxa, entrou em um loop de tentativa sem backoff e consumiu meu saldo restante de tokens antes que eu percebesse.

Correções Imediatas para Cada Modo de Falha

Limites de Taxa: Pare o Sangramento Primeiro

A correção imediata mais eficaz é o backoff exponencial com jitter. A ideia: cada tentativa espera o dobro do tempo da anterior, com um pequeno deslocamento aleatório (jitter) para distribuir as tentativas simultâneas de múltiplos clientes.

A parte do jitter é fácil de ignorar, mas é importante. Sem ele, quando múltiplos trabalhadores ou threads de agentes paralelos atingem o mesmo limite de taxa e depois todos tentam novamente exatamente no mesmo intervalo, você recria o problema de pico a cada ciclo de tentativa. Você não está resolvendo a questão — está apenas adiando-a por um deslocamento fixo.

Um padrão simples em Python que me serviu bem:

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 ressaltar: o SDK oficial do Python da Anthropic inclui lógica de tentativa automática incorporada por padrão. Ele tenta novamente em caso de erros 429 até 2 vezes com backoff exponencial. Para fluxos de trabalho de agentes em produção com requisitos maiores de tolerância a falhas, você normalmente vai querer configurar isso com um valor max_retries maior e sua própria lógica de jitter.

Além das tentativas, reduza o paralelismo. Se você tiver cinco threads de agentes fazendo chamadas à API Claude simultaneamente, e seu limite de taxa for 50 RPM com um pool de tokens compartilhado, você quase certamente vai colidir. Escalone as solicitações, agrupe sempre que possível e não presuma que a execução paralela escala linearmente com o throughput.

Limites de Uso: Não Reinicie Do Zero

Um estouro de limite no meio de uma tarefa é um dos modos de falha mais frustrantes porque o trabalho realizado antes do estouro de limite geralmente ainda é válido. A solução não é reiniciar — é salvar o estado e retomar.

Se você está em um plano de assinatura e atingindo limites com frequência em fluxos de trabalho de produção, a API Batch permite o processamento assíncrono de grandes volumes de solicitações com 50% de desconto tanto em tokens de entrada quanto de saída — o que aumenta significativamente sua capacidade efetiva para tarefas que não exigem latência. O cache de prompts vale a pena ser implementado se você tiver prompts de sistema grandes ou contexto repetido: tokens em cache custam uma fração dos tokens de entrada padrão, e em sessões longas de agentes, onde o mesmo contexto é re-enviado repetidamente, isso se acumula rapidamente.

Se o limite de uso for um descompasso estrutural — você realmente precisa de mais throughput do que seu nível atual proporciona — verifique os limites do plano atual em docs.anthropic.com/en/api/rate-limits antes de tomar decisões sobre o nível, já que esses números mudam sem aviso.

Tratamento de Interrupções: Degradação Graciosa

Para interrupções, os padrões principais são circuit breakers e degradação graciosa.

Padrões de circuit breaker têm três estados: Fechado (operação normal), Aberto (falhas detectadas — pare de tentar) e Meio-Aberto (testando se o serviço se recuperou). Aplicado a uma integração com a API Claude: após N falhas consecutivas, o circuito abre e para de enviar solicitações. Após um período de timeout, ele permite uma única solicitação de teste. Se essa solicitação tiver sucesso, o circuito fecha novamente.

A principal diferença de comportamento em relação às tentativas: tentativas lidam com falhas de requisições individuais, enquanto circuit breakers lidam com falhas sistêmicas. Se Claude estiver fora do ar por 20 minutos, você não quer que seu agente faça 400 chamadas de API falhas durante esse período. Você quer que ele detecte o padrão, pare de tentar, coloque o trabalho em fila e retome quando o serviço se recuperar.

Construindo Resiliência no Fluxo de Trabalho do Seu Agente

Esses padrões são onde a parte interessante está — pelo menos para mim. As correções imediatas acima param o sangramento. Esta seção é sobre não sangrar em primeiro lugar.

Roteamento de Modelo de Contingência

Quando o Claude não estiver disponível, ter um endpoint de modelo de contingência significa que seu agente pode continuar com capacidade reduzida em vez de parar completamente. A forma prática disso: seu fluxo de trabalho principal direciona para Claude; se você receber um 529 ou ocorrer um disparo do circuit breaker, você roteia para um modelo secundário para subtarefas de menor prioridade enquanto o trabalho crítico fica em fila para que Claude retome.

Isso não é algo simples de implementar — modelos diferentes têm comportamento diferente em chamadas de ferramentas, formatos de contexto e consistência de saída. Eu sugeriria começar com um escopo de contingência limitado: identifique as partes do fluxo de trabalho do seu agente que são realmente independentes do modelo (resumos, classificação simples, conversão de formato) e direcione estas para o modelo de contingência primeiro. Mantenha as etapas complexas e que exigem muito uso de ferramentas na fila.

Para roteamento multi-fornecedor com lógica de contingência adequada, o gateway LLM da Portkey cobre os padrões em detalhes — a combinação de tentativas, contingências e circuit breakers como um sistema em camadas vale a pena ser estudada se você está construindo para confiabilidade em produção.

Padrões de Checkpoint e Retomada

Esta parte eu ainda não decifrei completamente, sendo honesto. Mas a direção é clara: o estado do agente precisa ser serializável nas fronteiras das tarefas.

A forma básica: antes de uma chamada de API do Claude, serialize o estado atual do seu agente — progresso da tarefa, etapas concluídas, saídas intermediárias — para armazenamento persistente. Se a chamada falhar e o circuit breaker abrir, você tem um ponto de checkpoint de onde retomar em vez de começar do zero.

A parte mais difícil é definir "fronteiras de tarefa" em fluxos de trabalho agentivos onde as etapas são interdependentes. Eu descobri que a abordagem mais limpa é tratar cada chamada de ferramenta como um potencial checkpoint, mesmo que isso pareça granular. É mais fácil consolidar checkpoints do que desembaraçar uma tarefa multi-etapas parcialmente concluída sem ponto de recuperação.

Separando o Caminho Crítico das Tarefas de Fundo

Nem todas as tarefas do agente precisam das mesmas garantias de disponibilidade. Tarefas em segundo plano — registro, resumir, análise de baixa prioridade — podem tolerar que Claude fique indisponível por minutos ou horas. Tarefas do caminho crítico não podem.

Modelar isso explicitamente permite projetar diferentes perfis de resiliência: o caminho crítico recebe lógica de tentativa agressiva, modelos de fallback e monitoramento de disjuntor; tarefas em segundo plano são enfileiradas com paciência e sem pressão de tentativas. Isso por si só reduz significativamente o ruído causado pelos limites de uso do Claude, porque você não está mais tratando cada chamada de API falhada como igualmente urgente.

O Problema Mais Profundo: Cada Solução Alternativa é Redescoberta

Aqui está o que tem me incomodado nesse espaço inteiro.

Conversei com pessoas que construíram fluxos de trabalho baseados em Claude o suficiente para notar um padrão. Alguém resolve o problema do retrocesso exponencial. Eles implementam bem. Funciona. Então, três meses depois, um colega começa um novo projeto, encontra os mesmos erros 429 e resolve novamente — de uma forma ligeiramente diferente, em um arquivo ligeiramente diferente, de uma maneira ligeiramente diferente. A primeira solução nunca foi transferida.

O mesmo se aplica a padrões de checkpoint, configurações de disjuntor, lógica de roteamento de fallback. Um contador global de tentativas trata todas as ferramentas como um único domínio de falha — quando uma ferramenta degrada, esgota o orçamento para todas as outras ferramentas. Alguém descobre isso, cria disjuntores por ferramenta, e isso fica no código de um projeto, sem documentação, sem referência no próximo projeto que enfrenta exatamente o mesmo problema.

Isso não é um problema de código — é um problema de estrutura de conhecimento. Uma estratégia de fallback validada pertence a uma forma reutilizável que viaja junto com a capacidade do agente, não em um registro de chat ou em um script único que acaba esquecido.

Não tenho uma resposta completa para isso. Continuo pensando sobre isso.

Perguntas Frequentes

Quais são os limites de taxa atuais do Claude para usuários de API?

Eles mudam, então verifique na documentação oficial de limites de taxa da Anthropic antes de tomar decisões arquitetônicas. Como referência aproximada: os limites são baseados em níveis (Nível 1 a 4), medidos em RPM, ITPM e OTPM, com níveis mais altos liberando após atingir limites de gasto. O Nível 1 começa conservador; o Nível 4 é significativamente mais generoso. Números de artigos de 2025 provavelmente já estão desatualizados.

Como lidar com interrupções do Claude em um fluxo de trabalho de agente em produção?

Disjuntores são o padrão correto. Abra o circuito após um limite de falhas consecutivas, coloque o trabalho em fila durante o estado aberto, teste após um tempo limite, feche quando o serviço se recuperar. Verifique status.anthropic.com no seu monitoramento para distinguir um problema localizado de um incidente generalizado na plataforma.

Qual é o melhor modelo de fallback quando Claude não está disponível?

Não há uma resposta universal aqui — depende do que seu agente está fazendo. Para tarefas de saída estruturada, a maioria dos modelos mais capazes lida razoavelmente bem. Para cadeias complexas de uso de ferramentas e raciocínio em múltiplas etapas, a qualidade do fallback se degrada mais perceptivelmente. Comece identificando o segmento específico do seu fluxo de trabalho que é realmente independente do modelo e direcione isso para um fallback primeiro.

Como salvar o estado do agente para que uma falha do Claude não reinicie minha tarefa do zero?

Serialize o estado do agente nos limites das tarefas antes de cada chamada de API do Claude. No mínimo: passos concluídos, saídas intermediárias, posição atual no gráfico da tarefa. A questão da granularidade é mais difícil — incline-se para checkpoints mais frequentes. Armazenamento é barato; executar novamente uma tarefa de agente de duas horas não é.

Como evitar que meu agente queime tokens em tentativas falhas?

Duas coisas: backoff exponencial com jitter (para que as tentativas não criem picos sincronizados) e disjuntores (para que falhas sistêmicas não continuem consumindo o orçamento de tentativas). O SDK Python da Anthropic tem lógica básica de retry incorporada — configure explicitamente em vez de depender dos padrões. Para sistemas de produção com paralelismo, adicione disjuntores por ferramenta ou por operação para que um endpoint degradado não consuma todo o orçamento de retentativas.

Provavelmente continuarei observando como isso evolui. Os padrões de limite e resiliência parecem ainda estar sendo desenvolvidos publicamente, e não tenho certeza se já cheguei à versão mais limpa para fluxos de trabalho agenticos de longa duração. Mas a distinção entre os três modos de falha — pelo menos isso parece mais definido.