limite de uso do Claude: o que fazer

Quais são os limites de uso do Claude?

Os limites de uso do Claude operam em dois sistemas distintos. O primeiro passo é identificar qual deles interrompeu sua operação. Uma assinatura do Claude (Pro, Max, Team ou Enterprise) fornece uma cota de uso rotativa compartilhada entre os modelos e o Claude chat; o limite é atingido com uma mensagem como You've hit your session limit · resets 3:45pm. A API do Claude mede um parâmetro diferente: a velocidade de envio de requisições e tokens, contada por minuto. O limite é atingido com um erro HTTP 429 do tipo rate_limit_error e um header retry-after indicando quantos segundos aguardar.

As soluções para cada caso são diferentes. Um limite de assinatura refere-se ao volume de uso dentro de um intervalo de tempo; você deve aguardar o reset ou adquirir mais uso. Um limite de taxa (rate limit) da API refere-se à sua velocidade atual; o limite é liberado em segundos assim que você reduzir a frequência.

Os valores de cota dos planos e os níveis de rate limit mudam frequentemente. Como um valor incorreto é pior do que nenhum valor, nenhum número é impresso aqui. Consulte seus próprios valores utilizando os comandos abaixo.

Qual limite você atingiu? Leia a mensagem exata

O Claude Code identifica o sistema no texto exibido. Verifique o seu antes de alterar qualquer configuração.

• You've hit your session limit · resets 3:45pm é um limite de assinatura. O seu limite rotativo para este período foi esgotado.
• You've hit your weekly limit · resets Mon 12:00am é o mesmo sistema para o período de tempo mais longo.
• You've hit your Opus limit · resets 3:45pm é um limite de assinatura que se aplica apenas a requisições Opus. Este é o único caso em que a troca de modelo ajuda.
• API Error: Request rejected (429) · this may be a temporary capacity issue. If it persists, check https://status.claude.com. é um limite de taxa (rate limit) de API. Você atingiu o limite configurado para sua API key, ou para o seu projeto no Amazon Bedrock ou Google Cloud.
• API Error: Server is temporarily limiting requests (not your usage limit) é um throttle de curta duração não relacionado à sua cota do plano. O Claude Code tenta novamente automaticamente com backoff antes de exibir essa linha.

Limites de assinatura: sessão, semanal e a janela Opus

Um plano de assinatura inclui uma cota de uso rotativa. Quando esgotada, o Claude Code bloqueia novas requisições até o horário de reset indicado na mensagem. Duas propriedades dessa cota causam a maioria das confusões.

• A cota é compartilhada com o chat do Claude. O trabalho realizado em claude.ai consome a mesma cota do trabalho no terminal; portanto, um uso intenso no chat reduz o tempo disponível para codificação.
• A cota é compartilhada entre modelos. Os limites de sessão e semanais não possuem orçamento por modelo, com a única exceção do limite do Opus.

No Claude for Teams e Enterprise, o formato documentado é uma cota por usuário que reseta em uma janela rotativa de cinco horas e uma janela semanal. Essa cota é compartilhada com o Claude chat e Cowork, e o tamanho depende do nível do assento (Standard ou Premium). No Pro e Max, o horário de reset exibido na mensagem e as suas próprias barras /usage são os valores confiáveis, não dados extraídos de posts de blogs. Se você ainda estiver escolhendo um plano, qual plano do Claude você precisa compara as restrições de cada um.

Por que trocar o modelo com /model não restaura o acesso

Este é o erro mais comum, e a documentação é direta: os limites de sessão e semanais são compartilhados entre todos os modelos, portanto, trocar de modelo não restaura o acesso. Escolher um modelo menor após o fim da sua janela de sessão apenas altera qual modelo responderia. Isso não altera o quanto de cota resta, pois a cota não é mantida por modelo; logo, a troca não libera nada.

A exceção é o limite do Opus, que é um teto específico do modelo. Se a mensagem exibir You've hit your Opus limit, então /model é a correção correta. Mude para outro modelo e continue trabalhando, pois apenas as requisições do Opus foram bloqueadas.

Tratar o limite como um bug é o segundo erro comum. Reinstalar ou reautenticar não altera nada. A cota retorna quando a janela for resetada ou quando você comprar créditos de uso.

O que fazer ao atingir o limite de assinatura

1. Verifique o horário de reset. O intervalo de uma sessão é curto. O intervalo semanal não é algo para você esperar sentado em sua mesa.
2. Se for o limite do Opus, execute /model e escolha outro modelo.
3. Execute /usage para ver os limites do seu plano, seus créditos e quando eles resetam. /cost é um alias para a mesma tela.
4. Execute /usage-credits para continuar trabalhando após atingir o limite. No Pro e Max, ele abre suas configurações de faturamento. No Team e Enterprise, ele abre as configurações de uso da sua organização ou envia uma solicitação aos seus administradores caso você não tenha acesso ao faturamento.
5. Se você atingir o mesmo limite toda semana, o plano é inadequado para o seu fluxo de trabalho.

O /usage-credits requer uma assinatura do claude.ai iniciada via /login. Ele não está disponível com autenticação por API key, pois uma API key não possui cota de plano para expansão.

Créditos de uso possuem um efeito colateral importante. O tempo de vida do prompt cache é de uma hora em uma assinatura e cai para cinco minutos assim que você passa a usar créditos; portanto, mais turnos começam do zero e o uso de tokens do Claude Code aumenta para o mesmo volume de trabalho.

Mensagens que parecem limites de uso, mas não são

Quatro erros do Claude Code são reportados como limites de uso, mas nenhum deles é um limite real.

• Um aviso de context ou auto-compact não é um limite de uso. O /context imprime uma linha como Context exceeds the 200k-token limit by 94k tokens — run /compact or /clear to continue. quando a conversa excede a janela de contexto do modelo. O histórico antigo é resumido para liberar espaço, e o limite do seu plano não é afetado.
• Error during compaction: Conversation too long. Press esc twice to go up a few messages and try again. significa que o /compact falhou, pois não há contexto livre suficiente para conter o resumo que ele produziria.
• Credit balance is too low significa que sua organização no Console ficou sem créditos pré-pagos. Adicione créditos em platform.claude.com/settings/billing, que também oferece recarga automática.
• API Error: Usage credits required for 1M context · run /usage-credits to turn them on, or /model to switch to standard context é uma verificação de permissão, não uma cota esgotada. Escolha a variante do modelo sem o sufixo [1m] ou configure CLAUDE_CODE_DISABLE_1M_CONTEXT=1.

Outro erro vem da API. Um 413 request_too_large é um limite de tamanho para uma única requisição, não um limite de taxa (rate limit).

Limites de taxa da API: o que o erro 429 realmente contabiliza

A Messages API mede três métricas, separadamente para cada classe de modelo.

• requests per minute (RPM)
• input tokens per minute (ITPM)
• output tokens per minute (OTPM)

Sua organização também possui um limite de gastos, que é um conceito diferente: um custo mensal máximo para o uso da API. Ao atingir o teto de gastos do seu tier, o uso da API é pausado até o próximo mês, a menos que você solicite um limite maior. Nenhum loop de retry resolverá isso.

Quatro mecanismos determinam quando o erro 429 ocorre.

• Os limites são por classe de modelo. Eles se aplicam separadamente a cada modelo, permitindo o uso de diferentes modelos simultaneamente até seus respectivos limites. Algumas famílias compartilham um bucket: o limite de taxa do Opus é o total somado de Claude Opus 4.8, Opus 4.7, Opus 4.6 e Opus 4.5, enquanto o Claude Sonnet 5 possui o seu próprio.
• A capacidade é reabastecida continuamente. A API utiliza um algoritmo de token bucket, portanto, a capacidade é reposta continuamente em vez de resetar em um momento fixo. Um limite de 60 requests por minuto pode ser aplicado como um request por segundo; assim, 60 requests disparados de uma vez ainda falharão.
• Apenas inputs não em cache contam para o ITPM na maioria dos modelos. input_tokens e cache_creation_input_tokens contam. cache_read_input_tokens não conta na maioria dos modelos Claude, sendo o Claude Haiku 3.5 a exceção documentada. O uso de cache, portanto, proporciona margem de taxa (headroom) e também desconto. No output, um max_tokens alto não conta contra o OTPM, pois o OTPM contabiliza apenas os tokens efetivamente produzidos.
• Os limites residem no nível da organização. Um workspace pode receber um limite menor, e os limites da organização sempre se aplicam, mesmo que a soma dos limites dos workspaces seja maior. Um limite que não foi sobrescrito em um workspace é herdado da organização, não ficando ilimitado.

Os tiers Start, Build, Scale e Custom definem os valores reais, atribuídos automaticamente com base no seu histórico de uso e status da conta. Novas organizações podem começar abaixo dos limites padrão publicados, portanto, um primeiro 429 pode ocorrer antes do previsto em uma tabela. Um aumento súbito no uso aciona limites de aceleração, que retornam 429 mesmo que você ainda esteja dentro do seu tier; por isso, aumente o tráfego gradualmente. Todo valor publicado é um teto: os limites documentados são o uso máximo permitido, não mínimos garantidos. Para solicitar mais, use o controle "Request rate limit increase" na página Limits no Claude Console.

Lendo um 429: retry-after, os headers e retentativas do SDK

Todo erro de API retorna o mesmo envelope: um objeto error aninhado contendo o tipo e a mensagem, além de um request_id de nível superior.

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "<names the rate limit you exceeded>"
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}

Os headers contêm o restante.

• retry-after é o número de segundos para aguardar antes de tentar a requisição novamente. Retentativas antecipadas falharão.
• anthropic-ratelimit-requests-limit, anthropic-ratelimit-requests-remaining e anthropic-ratelimit-requests-reset descrevem o seu orçamento de requisições (request budget).
• anthropic-ratelimit-input-tokens-* e anthropic-ratelimit-output-tokens-* fazem o mesmo para ITPM e OTPM, com os mesmos sufixos limit, remaining e reset.
• anthropic-ratelimit-tokens-* exibe os valores para o limite mais restritivo em vigor no momento.

Headers de reset são timestamps RFC 3339. Headers de tokens restantes são arredondados para o milhar mais próximo; use-os apenas como referência. O modo Fast possui seu próprio pool e seus próprios headers anthropic-fast-*. Leia todos eles em qualquer chamada bem-sucedida:

curl -s -D - -o /dev/null https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":16,"messages":[{"role":"user","content":"hi"}]}' \
  | grep -i 'ratelimit\|retry-after\|request-id'

Cada resposta também contém um header request-id único, como req_018EeWyXxfu5pfWkrYcMdjWG. Ele aparece como request_id nos corpos de erro e como _request_id nas respostas dos SDKs Python e TypeScript. Utilize este valor ao entrar em contato com o suporte.

Verifique se você realmente precisa de um loop de backoff antes de implementá-lo. Os SDKs oficiais realizam retentativas automáticas para falhas transitórias, incluindo erros de conexão, limites de taxa (rate limits) e erros de servidor 5xx, utilizando exponential backoff, duas vezes por padrão, respeitando o header retry-after quando presente. Cada cliente aceita uma opção de maximum-retries para alterar ou desativar esse comportamento.

import anthropic

client = anthropic.Anthropic(max_retries=5)  # the SDK default is 2

try:
    msg = client.messages.create(
        model="claude-sonnet-5",
        max_tokens=1024,
        messages=[{"role": "user", "content": "hello"}],
    )
except anthropic.RateLimitError as err:
    headers = err.response.headers
    print("still limited after retries; wait", headers.get("retry-after"), "seconds")
    print("request id:", headers.get("request-id"))

529 overloaded_error não é culpa sua

Um erro 429 indica que você excedeu o limite de requisições. Um erro 529 overloaded_error indica que a API está temporariamente sobrecarregada; isso ocorre quando a API recebe alto tráfego de todos os usuários. O problema não é causado pela sua chave ou pelo seu código. Tente novamente usando exponential backoff, que os SDKs já aplicam para respostas 5xx, e verifique status.claude.com se o erro persistir. Um erro 500 api_error é um erro interno que deve ser tratado da mesma forma, e nenhum dos dois é um limite de taxa (rate limit).

Leia seus próprios limites em vez de uma tabela

Em uma assinatura, a tela /usage é a mais importante. Ela exibe as barras de uso do seu plano e o detalhamento do que consumiu os recursos. Os botões d ou w alternam entre as últimas 24 horas e os últimos 7 dias. Dois avisos. O bloco Session mostra o uso de tokens de API e é destinado a usuários de API; assinantes podem ignorar o valor em dólares. Os números vêm do histórico de sessão local dessa máquina, portanto, o uso de outro dispositivo ou do claude.ai não é contabilizado.

No lado da API, a página Usage no Claude Console exibe dois gráficos: "Rate Limit - Input Tokens" e "Rate Limit - Output Tokens". O gráfico de input plota o máximo horário de tokens de input não armazenados em cache por minuto contra o seu limite atual de ITPM, com sua taxa de cache ao lado. Isso permite monitorar a aproximação de um limite antes que ele ocorra em produção.

Para ler seus limites configurados programaticamente:

curl -s https://api.anthropic.com/v1/organizations/rate_limits \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  -H "anthropic-version: 2023-06-01"

É necessária uma chave Admin API, e o GET /v1/organizations/workspaces/{workspace_id}/rate_limits faz o mesmo por workspace. Ambos são apenas leitura: para alterar um limite, use a aba Limits no Console.

Usando menos para evitar limites

Ambos os sistemas monitoram a mesma métrica internamente, portanto estas configurações funcionam em ambos.

• Gaste menos tokens por turno. Sessões contínuas mantêm o cache aquecido, e /clear entre tarefas não relacionadas não tem custo adicional. Uso de tokens do Claude Code detalha todas essas configurações.
• Reduza o esforço. Os níveis são low, medium, high, xhigh e max. O menu /effort também oferece ultracode, que aumenta o gasto em vez de reduzi-lo. Raciocínio profundo para renomear arquivos mecânicos é desnecessário.
• Reduza a concorrência após um erro 429. Diminua o CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY e evite muitos subagentes paralelos. Use também o /status: um ANTHROPIC_API_KEY perdido roteia requisições via uma chave de nível baixo em vez da sua assinatura.
• Mova trabalhos não interativos para a Message Batches API. Ela processa grandes volumes de forma assíncrona com 50% de desconto em tokens de input e output, sob limites de taxa próprios, evitando que jobs noturnos compitam com sua sessão.

Trabalhos intermitentes executados por programas em vez de pessoas devem usar uma API key desde o início. Seu primeiro app Claude API em um VPS aborda o gerenciamento de chaves e retentativas, e uma execução longa de agente sobrevive a uma queda de conexão se você mantiver o Claude Code rodando em um VPS dentro do tmux.

FAQ

Por que trocar de modelo não resolve meu limite de uso do Claude?

Porque os limites de sessão e semanais são compartilhados entre todos os modelos. A cota pertence ao plano, não ao modelo; portanto, /model altera apenas qual modelo responderá, não quanto resta de cota. A única exceção é o You've hit your Opus limit, que se aplica apenas a requisições Opus. Nesse caso, trocar de modelo é a solução documentada.

O que significa o erro 429 rate_limit_error e quanto tempo devo esperar?

Significa que sua conta atingiu um limite de taxa para aquela classe de modelo: requisições por minuto, tokens de entrada por minuto ou tokens de saída por minuto. A resposta contém um header retry-after com os segundos de espera, e tentativas antecipadas falharão. Os SDKs oficiais já realizam retentativas para rate limits e erros 5xx com exponential backoff, duas vezes por padrão, respeitando esse header. Um erro 429 que ocorre enquanto você ainda está dentro dos limites do seu tier indica um limite de aceleração devido a um aumento súbito de demanda.

Como vejo meus limites de uso do Claude e quando eles resetam?

No Claude Code, execute /usage para ver as barras do seu plano, horários de reset e o detalhamento de uso; /cost é um alias, e d ou w alterna entre as últimas 24 horas e os últimos 7 dias. Esses dados vêm do histórico de sessão local, portanto, não incluem o uso de outros dispositivos ou do claude.ai. Na API, o Console exibe seus rate limits, e o comando GET /v1/organizations/rate_limits retorna seus limites configurados usando uma chave Admin API.

Posso continuar trabalhando após atingir o limite do meu plano Claude?

Às vezes. Execute /usage-credits para comprar uso adicional além do teto nos planos Pro e Max, ou para solicitar a um administrador nos planos Team e Enterprise; isso requer um login no claude.ai via /login e não está disponível para autenticação via API key. Caso contrário, aguarde o horário de reset, troque de modelo se o limite atingido foi o do Opus, ou transfira o trabalho para uma API key, que contabiliza o uso por minuto em vez de por janela de tempo.