Limite de uso do Claude: o que fazer depois

Quais são os limites de utilização do Claude?

Os limites de utilização do Claude estão divididos em dois sistemas distintos. O primeiro passo é identificar qual deles bloqueou o acesso. Uma subscrição do Claude (Pro, Max, Team ou Enterprise) fornece uma quota de utilização contínua, partilhada entre os modelos e com o chat do Claude. Quando essa quota é excedida, o serviço apresenta uma mensagem como You've hit your session limit · resets 3:45pm. A API do Claude mede outra coisa: a velocidade a que envia pedidos e tokens, contabilizada por minuto. Quando esse limite é excedido, a API devolve um erro HTTP 429 do tipo rate_limit_error e um cabeçalho retry-after que indica quantos segundos deve aguardar.

As correções são completamente diferentes. Um limite da subscrição depende da quantidade utilizada dentro de uma janela. Nesse caso, aguarde pela reposição da quota ou compre mais utilização. Um limite de taxa da API depende da velocidade atual dos pedidos. É eliminado em poucos segundos depois de reduzir essa velocidade.

As quotas dos planos e os números dos níveis de limite de taxa mudam com frequência. Um número incorreto é pior do que nenhum número, por isso não são apresentados aqui. Consulte os seus valores com os comandos mais abaixo.

Qual limite atingiu? Leia a mensagem exata

O Claude Code identifica o sistema no texto que apresenta. Confirme qual é o seu antes de alterar qualquer coisa.

• You've hit your session limit · resets 3:45pm é um limite da subscrição. O limite contínuo do seu plano para esta janela foi consumido.
• You've hit your weekly limit · resets Mon 12:00am é o mesmo sistema numa janela mais longa.
• You've hit your Opus limit · resets 3:45pm é um limite da subscrição aplicável apenas a pedidos ao Opus. Este é o único caso em que mudar 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 da API. Atingiu o limite configurado para a sua chave da API ou para o seu projeto Amazon Bedrock ou Google Cloud. Qual deles se aplica depende de como o cliente autentica, porque um cliente Bedrock ou Vertex é contabilizado na quota do seu projeto cloud e não numa organização Anthropic.
• API Error: Server is temporarily limiting requests (not your usage limit) é uma limitação temporária de curta duração, sem relação com a quota do seu plano. O Claude Code tenta novamente automaticamente com um intervalo crescente antes de apresentar essa linha.

Limites da subscrição: sessão, semana e a janela do Opus

Um plano de subscrição inclui uma margem de utilização contínua. Quando essa margem se esgota, o Claude Code bloqueia novos pedidos até à hora de reposição apresentada na mensagem. Duas propriedades dessa margem causam a maior parte da confusão.

• É partilhada com o Claude chat. O trabalho feito em claude.ai consome a mesma margem que o trabalho no terminal, pelo que uma tarde de utilização intensa no chat reduz o tempo disponível para programar à noite. Todas as interfaces em que inicia sessão com essa conta consomem o mesmo conjunto de utilização. Assim, no Linux, a aplicação de ambiente de trabalho beta e a CLI do Claude Code partilham uma margem, em vez de terem uma margem cada uma.
• É partilhada entre modelos. Os limites de sessão e semanais não têm um orçamento por modelo. A única exceção é o limite do Opus.

No Claude for Teams e Enterprise, a estrutura documentada consiste numa margem por lugar que é reposta numa janela contínua de cinco horas e numa janela semanal. Essa margem é partilhada com o Claude chat e o Cowork e o seu tamanho depende do nível do lugar (Standard ou Premium). No Pro e Max, a hora de reposição apresentada na mensagem e as suas próprias barras /usage são os valores fiáveis. Não use um valor copiado de uma publicação de blogue. Se ainda estiver a escolher um nível, qual o plano Claude de que precisa compara o que cada um permite.

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

Esta é a medida errada mais comum, e a documentação é clara: os limites da sessão e semanais são partilhados por todos os modelos, portanto trocar de modelo não restaura o acesso. Selecionar um modelo menor depois de esgotar a janela da sessão altera o modelo que responderia. Não altera o saldo disponível, porque o saldo nunca foi mantido por modelo. Por isso, a troca não tem nada para libertar.

A exceção é o limite do Opus, que é um limite específico do modelo. Se a mensagem for You've hit your Opus limit, então /model é a correção correta. Troque para outro modelo e continue a trabalhar, porque apenas os pedidos ao Opus foram bloqueados.

Considerar que o limite é um erro é a segunda medida errada. Reinstalar ou autenticar novamente não altera nada. O saldo volta quando a janela for reposta ou quando comprar créditos de utilização.

O que fazer quando atingir um limite da subscrição

1. Consulte a hora de reposição. Uma janela de sessão é curta. Uma janela semanal não é algo que se espere à secretária.
2. Se for o limite do Opus, execute /model e escolha outro modelo.
3. Execute /usage para ver os limites do seu plano, as barras e a hora de reposição. /cost é um alias para o mesmo ecrã.
4. Execute /usage-credits para continuar a trabalhar depois de atingir o limite. Nos planos Pro e Max, abre as definições de faturação. Nos planos Team e Enterprise, abre as definições de utilização da sua organização ou envia um pedido aos administradores se não tiver acesso à faturação.
5. Se atingir o mesmo limite todas as semanas, o plano não tem a dimensão adequada à forma como trabalha. Vale a pena avaliar as formas de ultrapassar um limite de utilização uma vez, em vez de o fazer a cada reposição.

/usage-credits requer uma subscrição do claude.ai com sessão iniciada através de /login. Não está disponível com autenticação por chave de API, porque uma chave de API não tem uma franquia de plano que possa ser aumentada.

Os créditos de utilização têm um efeito secundário que convém conhecer primeiro. A duração da cache de prompts é de uma hora numa subscrição e passa para cinco minutos quando começa a utilizar créditos. Assim, mais interações começam sem cache e o consumo de tokens do Claude Code aumenta para o mesmo trabalho.

Mensagens que parecem limites de utilização, mas não são

Quatro erros do Claude Code são comunicados como limites de utilização, mas nenhum deles é um.

• Um aviso de contexto ou de compactação automática não é um limite de utilização. /context apresenta uma linha como Context exceeds the 200k-token limit by 94k tokens — run /compact or /clear to continue. quando a conversa ultrapassa a janela de contexto do modelo. O histórico mais antigo é resumido para libertar 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 próprio /compact falhou, porque já não há contexto livre suficiente para armazenar o resumo que produziria.
• Credit balance is too low significa que a sua organização do Console ficou sem créditos pré-pagos. Adicione créditos em platform.claude.com/settings/billing, onde também pode ativar o recarregamento automático.
• 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 elegibilidade, não uma quota esgotada. Selecione a variante do modelo sem o sufixo [1m] ou defina CLAUDE_CODE_DISABLE_1M_CONTEXT=1.

Há ainda um caso proveniente da API. Um erro 413 request_too_large indica um limite de tamanho para um único pedido, não um limite de taxa.

Limites de taxa da API: o que o 429 está realmente a contabilizar

A Messages API mede três coisas, separadamente para cada classe de modelo.

• pedidos por minuto (RPM)
• tokens de entrada por minuto (ITPM)
• tokens de saída por minuto (OTPM)

A sua organização também tem um limite de gastos, que é diferente: um custo mensal máximo para a utilização da API. Quando atingir o limite de gastos do seu nível, a utilização da API é suspensa até ao mês seguinte, a menos que peça um limite superior. Nenhum ciclo de novas tentativas resolve essa situação.

Quatro mecanismos determinam quando chega o 429.

• Os limites são por classe de modelo. Aplicam-se separadamente a cada modelo, pelo que pode utilizar modelos diferentes em simultâneo até aos respetivos limites. Algumas famílias partilham um bucket: o limite de taxa do Opus é um total para Claude Opus 4.8, Opus 4.7, Opus 4.6 e Opus 4.5, enquanto Claude Sonnet 5 tem o seu próprio limite.
• A capacidade é reposta continuamente. A API utiliza um algoritmo de token bucket, pelo que a capacidade é reposta continuamente, em vez de ser reiniciada num momento fixo. Um limite de 60 pedidos por minuto pode ser aplicado como um pedido por segundo, pelo que 60 pedidos enviados de uma vez continuam a falhar.
• Na maioria dos modelos, apenas os tokens de entrada não colocados em cache contam para o ITPM. input_tokens e cache_creation_input_tokens contam. cache_read_input_tokens não conta na maioria dos modelos Claude, sendo Claude Haiku 3.5 a exceção documentada. O caching proporciona, portanto, margem adicional no limite de taxa, além de um desconto. No lado da saída, um valor elevado de max_tokens não conta para o OTPM, porque o OTPM contabiliza apenas os tokens efetivamente produzidos.
• Os limites existem ao nível da organização. Pode ser atribuído um limite inferior a um workspace, e os limites de toda a organização aplicam-se sempre, mesmo que a soma dos limites dos workspaces seja superior. Um limite que não tenha substituído num workspace é herdado da organização, não fica sem limite.

Os níveis Start, Build, Scale e Custom definem os valores efetivos. São atribuídos automaticamente com base no histórico de utilização e na situação da conta. As organizações novas podem começar abaixo dos limites padrão publicados, pelo que o primeiro 429 pode chegar mais cedo do que uma tabela prevê. Um aumento acentuado da utilização ativa limites de aceleração, que devolvem 429 mesmo quando ainda está dentro do seu nível. Por isso, aumente gradualmente o tráfego. Todos os valores publicados são limites máximos: os limites documentados representam a utilização máxima permitida, não mínimos garantidos. Para pedir um valor superior, utilize o controlo "Request rate limit increase" na página Limits da Claude Console.

Interpretando um 429: retry-after, cabeçalhos e novas tentativas do SDK

Todos os erros da API devolvem o mesmo envelope: um objeto error aninhado que contém o tipo e a mensagem, além de um request_id no nível superior.

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

Os restantes dados estão nos cabeçalhos.

• retry-after é o número de segundos a aguardar antes de poder repetir o pedido. As tentativas antecipadas falham.
• anthropic-ratelimit-requests-limit, anthropic-ratelimit-requests-remaining e anthropic-ratelimit-requests-reset descrevem o orçamento do seu pedido.
• anthropic-ratelimit-input-tokens-* e anthropic-ratelimit-output-tokens-* fazem o mesmo para ITPM e OTPM, com os mesmos sufixos de limite, valor restante e reset.
• anthropic-ratelimit-tokens-* apresenta os valores do limite mais restritivo atualmente em vigor.

Os cabeçalhos de reset contêm timestamps RFC 3339. Os cabeçalhos de tokens restantes são arredondados para o milhar mais próximo, por isso devem ser tratados como um indicador aproximado. O modo rápido tem o seu próprio conjunto e os seus próprios cabeçalhos anthropic-fast-*. Leia todos estes valores a partir de 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'

Todas as respostas também contêm um cabeçalho request-id exclusivo, como req_018EeWyXxfu5pfWkrYcMdjWG. Nos corpos de erro, ele aparece como request_id; nas respostas dos SDKs Python e TypeScript, aparece como _request_id. Inclua esse valor ao contactar o suporte.

Antes de escrever um ciclo de backoff, confirme se realmente precisa dele. Os SDKs oficiais repetem automaticamente as tentativas após falhas transitórias, incluindo erros de ligação, limites de pedidos e erros de servidor 5xx, usando backoff exponencial. Por predefinição, fazem duas novas tentativas e respeitam o cabeçalho retry-after quando este está presente. Cada cliente aceita uma opção de máximo de tentativas 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 é causado por si

Um erro 429 indica que os pedidos foram enviados demasiado depressa. Um erro 529 overloaded_error indica que a API está temporariamente sobrecarregada. Pode ocorrer quando a API recebe muito tráfego de todos os utilizadores. A sua chave e o seu código não causaram o problema. Tente novamente com recuo exponencial. Os SDKs já fazem isso para respostas 5xx. Se o problema não desaparecer, consulte status.claude.com. Um erro 500 api_error indica um erro interno. Tente novamente da mesma forma. Nenhum dos dois erros é um limite de taxa.

Leia os seus próprios limites em vez de consultar uma tabela

Numa subscrição, /usage é o ecrã relevante. Apresenta as barras de utilização do seu plano e uma discriminação do que as consumiu, e d ou w alterna entre as últimas 24 horas e os últimos 7 dias. Há duas ressalvas. O bloco Session mostra a utilização de tokens de API e destina-se a utilizadores da API, por isso os subscritores podem ignorar o valor em dólares. Os números vêm do histórico local de sessões nessa máquina, por isso a utilização noutro dispositivo ou em claude.ai não é incluída.

No lado da API, a página Usage na Claude Console apresenta dois gráficos: "Rate Limit - Input Tokens" e "Rate Limit - Output Tokens". O gráfico de entrada mostra o máximo horário de tokens de entrada não armazenados em cache por minuto em comparação com o seu limite ITPM atual, com a sua taxa de cache ao lado. Assim, pode acompanhar a aproximação ao limite em vez de só o descobrir em produção.

Para consultar programaticamente os limites configurados:

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 da Admin API, e GET /v1/organizations/workspaces/{workspace_id}/rate_limits faz o mesmo para cada workspace. Ambos são apenas de leitura. Para alterar um limite, utilize o separador Limits na Console.

Usar menos para ficar dentro de mais limites

Ambos os sistemas contabilizam a mesma coisa internamente, por isso estas opções funcionam em qualquer um deles.

• Gaste menos tokens por turno. Sessões contínuas mantêm a cache aquecida, e /clear entre tarefas não relacionadas não tem custo. O uso de tokens do Claude Code explica estas opções em detalhe.
• 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 consumo em vez de o reduzir. O raciocínio profundo não traz benefícios numa renomeação mecânica.
• Reduza a simultaneidade depois de um 429. Diminua CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY e evite muitos subagentes em paralelo. Execute também /status: um ANTHROPIC_API_KEY perdido encaminha os pedidos através de uma chave de nível inferior em vez da sua subscrição.
• Mova o trabalho não interativo para a Message Batches API. Ela processa grandes volumes de forma assíncrona, com um desconto de 50% nos tokens de entrada e saída e limites de taxa próprios. Assim, uma tarefa noturna deixa de competir com a sua sessão.

O trabalho que despeja dados no contexto é o mais afetado: se estiver a analisar ações e opções com dados de mercado em tempo real, obter apenas o subconjunto necessário para cada pergunta custa uma fração do que custa colar tabelas completas de cotações e cadeias de opções. O trabalho em picos, executado por um programa em vez de uma pessoa, deve usar uma chave de API desde o início. A mudança também altera a forma de pagamento e de contabilização, porque a Claude API não tem um nível gratuito além do pequeno crédito concedido no registo. A sua primeira aplicação da Claude API num VPS explica a gestão de chaves e as tentativas de repetição. Uma execução longa de um agente sobrevive a uma ligação interrompida se mantiver o Claude Code em execução num VPS dentro do tmux.

FAQ

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

Porque os limites de sessão e semanais são partilhados por todos os modelos. A franquia pertence ao plano, não a um modelo. Por isso, /model altera o modelo que responderia, mas não a franquia restante. A única exceção é You've hit your Opus limit, que se aplica apenas a pedidos ao Opus. Nesse caso, mudar de modelo é a correção documentada.

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

Significa que a sua conta atingiu um limite de taxa para essa classe de modelo: pedidos por minuto, tokens de entrada por minuto ou tokens de saída por minuto. A resposta inclui um cabeçalho retry-after com o número de segundos de espera, e as tentativas anteriores falham. Os SDKs oficiais já repetem automaticamente os pedidos após limites de taxa e erros 5xx, duas vezes por predefinição, respeitando esse cabeçalho. Um erro 429 que ocorre enquanto ainda está dentro dos limites do seu tier indica um limite de aceleração causado por um aumento súbito.

Como vejo os meus limites de uso do Claude e quando são repostos?

No Claude Code, execute /usage para ver as barras do seu plano, os horários de reposição e um resumo do uso; /cost é um alias, e d ou w alterna entre as últimas 24 horas e os últimos 7 dias. Esses valores vêm do histórico de sessões local. Por isso, não incluem o uso de outros dispositivos nem de claude.ai. Na API, a Console apresenta gráficos dos seus limites de taxa, e GET /v1/organizations/rate_limits devolve os limites configurados quando é usada uma chave da Admin API.

Posso continuar a trabalhar depois de atingir o limite do meu plano Claude?

Às vezes. Execute /usage-credits para comprar uso além do limite nos planos Pro e Max ou para o solicitar a um administrador nos planos Team e Enterprise. É necessário iniciar sessão no claude.ai através de /login, e esta opção não está disponível com autenticação por chave da API. Caso contrário, aguarde pelo horário de reposição, mude de modelo se tiver atingido o limite do Opus ou transfira o trabalho para uma chave da API, que mede o uso por minuto em vez de por janela.