Limite de uso do Claude: o que fazer quando atingir

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

Os limites de utilização do Claude pertencem a dois sistemas diferentes. O primeiro passo é identificar qual deles o bloqueou. Uma subscrição do Claude (Pro, Max, Team ou Enterprise baseado em lugares) fornece uma utilização disponível contínua, partilhada entre modelos, com exceção de alguns limites específicos por família de modelos, e partilhada com o Claude Chat. Quando esse limite é atingido, é apresentada uma mensagem como You've hit your session limit · resets 3:45pm. Os planos Enterprise atuais baseados na utilização são a exceção: não incluem qualquer utilização, e toda a utilização é faturada às tarifas da API desde o primeiro token. A API do Claude mede outra coisa: a velocidade a que envia pedidos e tokens, contabilizada por minuto. Quando esse limite é atingido, a API responde com um erro HTTP 429 do tipo rate_limit_error, normalmente com um cabeçalho retry-after que indica quantos segundos deve aguardar.

As formas de resolver estes limites são completamente diferentes. O limite de uma subscrição depende da quantidade utilizada durante uma janela de tempo. Nesse caso, deve aguardar pela reposição, comprar mais utilização ou gastar uma reposição gratuita do limite, se o seu plano tiver disponibilizado uma. O limite de taxa da API depende da velocidade atual dos pedidos. É removido em poucos segundos quando reduz a velocidade.

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

Que limite foi atingido? 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 progressivo do seu plano para esta janela foi esgotado.
• 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 Opus. Mudar para um modelo fora da família Opus permite continuar a trabalhar.
• You've hit your Sonnet limit · resets 3:45pm é o mesmo tipo de limite por família de modelos, aplicável apenas a pedidos Sonnet. Mudar para um modelo fora da família Sonnet permite continuar a trabalhar.
• Uma mensagem que começa por Fable limit reached significa que utilizou a parte do seu limite semanal que os modelos Fable podem consumir. Continuar com Fable gera custos de créditos de utilização, por isso o Claude Code pede confirmação primeiro. Escolha outro modelo com /model para permanecer dentro do seu plano.
• 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. A opção aplicável depende de como o cliente se 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 e breve, sem relação com a quota do seu plano. O Claude Code tenta novamente de forma automática, com backoff, antes de apresentar essa linha.

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

Um plano Pro, Max, Team ou Enterprise baseado em lugares inclui uma franquia de utilização contínua. Quando a franquia se esgota, o Claude Code bloqueia novos pedidos até à hora de reposição apresentada na mensagem. Duas características dessa franquia causam a maior parte da confusão.

• A franquia é partilhada com o Claude chat. O trabalho realizado em claude.ai consome a mesma franquia que o trabalho no terminal, por isso 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 a mesma reserva. No Linux, a aplicação de desktop beta e a CLI do Claude Code partilham uma franquia, em vez de terem uma cada uma.
• A franquia é partilhada entre modelos. Os limites de sessão e semanais pertencem a uma única reserva para todos os modelos. As exceções são os limites por família de modelos dentro dessa reserva: os limites do Opus e do Sonnet e, nos lugares Max e Premium, uma alocação Fable de até 50% dos limites semanais. Nos lugares Pro e Standard, o Fable não está incluído nos limites do plano e é cobrado aos créditos de utilização desde o primeiro pedido.

No Claude for Teams e no Enterprise baseado em lugares, o modelo documentado consiste numa franquia por lugar que é reposta numa janela contínua de cinco horas e numa janela semanal. Essa franquia é partilhada com o Claude chat e o Cowork e é definida pelo nível do lugar (Standard ou Premium). Os planos Enterprise atuais baseados na utilização funcionam de forma diferente: não existe uma franquia incluída que possa esgotar-se, a utilização é cobrada às tarifas da API e o limite é definido pelos limites de despesa configurados pelos administradores ao nível da organização e para utilizadores individuais. Num plano assistido pela equipa comercial, a utilização interrompida por um limite de despesa é retomada no início do período de faturação seguinte, exceto se um proprietário aumentar primeiro o limite. Num plano self-serve, a utilização também é interrompida quando o saldo de créditos pré-pagos se esgota, até que um proprietário compre mais créditos. No Pro e no Max, a hora de reposição apresentada na mensagem e as suas próprias barras /usage são os valores fiáveis, não um número copiado de uma publicação num blogue. Se ainda estiver a escolher um nível, qual o plano Claude de que precisa compara as restrições de cada opção.

Por que mudar de modelo com /model não restaura uma sessão nem o limite semanal

Esta é a ação incorreta mais comum, e a documentação é clara: os limites de sessão e semanais são partilhados por todos os modelos, por isso mudar de modelo não restaura o acesso. Escolher um modelo menor depois de esgotar a janela da sessão altera o modelo que responderia. Não altera o saldo disponível, porque os limites de sessão e semanais não são mantidos por modelo. Portanto, a mudança não tem nada para libertar.

As exceções são os limites da família de modelos. Se a mensagem for You've hit your Opus limit ou You've hit your Sonnet limit, então /model é a correção adequada. Mude para um modelo fora dessa família e continue a trabalhar, porque apenas os pedidos dessa família foram bloqueados. O limite do Fable nos planos Max e Premium funciona da mesma forma: mude para outro modelo para continuar a trabalhar dentro do seu plano ou continue a usar o Fable com créditos de utilização. No entanto, o Fable consome o conjunto semanal partilhado mais rapidamente do que os outros modelos. Por isso, mudar de modelo depois de atingir o limite do Fable nunca permite ultrapassar o limite semanal global.

Considerar o limite um erro é a segunda ação incorreta. Reinstalar ou voltar a autenticar-se não altera nada. O saldo é reposto quando a janela é reiniciada, quando utiliza uma reposição gratuita do limite ou quando compra créditos de utilização.

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

1. Consulte a hora do reset. Uma janela de sessão é curta. Uma janela semanal não é algo que deva esperar à secretária. No Claude Code v2.1.234 ou posterior, /rate-limit-options pode esperar pelo reset e continuar automaticamente a tarefa interrompida.
2. Se for o limite do Opus, Sonnet ou Fable, execute /model e escolha um modelo fora dessa família.
3. Execute /usage para ver os limites do seu plano, as barras de utilização e a hora do próximo reset. /cost é um alias para o mesmo ecrã.
4. Consulte Settings > Usage em claude.ai ou no Claude Desktop e procure a secção Resets. Ocasionalmente, os planos elegíveis recebem uma reposição gratuita do limite. Ao clicar em "Reset for free", o limite da sessão de cinco horas ou o limite semanal, consoante o que a oferta abranger, volta imediatamente ao valor total. O botão não está disponível no Claude Code num terminal ou IDE, nem no Claude Mobile, e cada oferta expira.
5. Execute /usage-credits para continuar a trabalhar depois de atingir o limite. Nos planos Pro e Max, este comando abre as definições de faturação. Nos planos Team e Enterprise, abre as definições de utilização da organização ou envia um pedido aos administradores se não tiver acesso à faturação.
6. Se atingir o mesmo limite todas as semanas, o plano não tem a dimensão adequada à forma como trabalha. Nesse caso, vale a pena avaliar uma vez as opções para ultrapassar um limite de utilização, em vez de o fazer a cada reset.

/usage-credits precisa de uma subscrição do claude.ai autenticada 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 prolongada.

Os créditos de utilização têm um efeito secundário que deve conhecer. Por predefinição, o Claude Code fornece à conversa principal uma cache de prompts com validade de uma hora enquanto estiver dentro da utilização incluída na subscrição. Quando começa a utilizar créditos, essa validade passa para cinco minutos. Assim, mais turnos começam sem cache e o consumo de tokens do Claude Code aumenta para o mesmo trabalho. Os subagentes ficam fora desse grupo da conversa principal, por isso têm cinco minutos mesmo dentro da utilização do plano. Se escolher manualmente o TTL, com a definição promptCacheTtl ou CLAUDE_CODE_PROMPT_CACHE_TTL no Claude Code v2.1.242 ou posterior, mantém a validade de uma hora enquanto utiliza créditos.

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 aviso de contexto ou de compactação automática não é um limite de uso. /context imprime uma linha como Context exceeds the 200k-token limit by 94k tokens, seguida do comando que liberta espaço, quando a conversa ultrapassa a janela de contexto do modelo. A compactação resume o histórico mais antigo para libertar espaço, mas não é gratuita: /compact lê a conversa que resume, portanto compactar um contexto grande é, por si só, um pedido grande contra o seu plano. Quando pretende começar de novo em vez de manter a continuidade, /clear não tem custo.
• Prompt is too long · automatic compaction failed: <the underlying error> significa que a própria compactação automática falhou devido ao erro indicado. /compact continua a falhar com o mesmo erro até o resolver.
• Credit balance is too low significa que a organização no Console esgotou os créditos pré-pagos ou que o Claude Code está a enviar os pedidos de um subscritor através de uma chave de API do Console; /status mostra qual é a credencial ativa. Adicione créditos em platform.claude.com/settings/billing, que também disponibiliza o carregamento automático.
• API Error: Usage credits required for 1M context · run /usage-credits to turn them on (they take effect after you restart Claude Code), or /model to switch to standard context é uma verificação de direitos de acesso, não uma quota esgotada. Se selecionou uma variante [1m] do Opus 4.6 ou Sonnet 4.6, escolha a variante sem o sufixo [1m] ou defina CLAUDE_CODE_DISABLE_1M_CONTEXT=1. Se aparecer a meio de uma conversa porque o contexto ultrapassou 200K tokens, o Claude Code compacta-o novamente para ficar abaixo do limite padrão. O Sonnet 5 e versões posteriores, o Opus 4.7 e versões posteriores, o Haiku 5.5 e os modelos Fable funcionam com uma janela nativa de 1M e não têm nenhum sufixo a remover; essa variável é que os limita a 200K.

Outro erro vem da API. Um 413 request_too_large é um limite de tamanho de um único pedido, não um limite de taxa.

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

A Messages API mede três valores, 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 despesa, que é diferente: um custo mensal máximo para a utilização da API. Quando atinge o limite de despesa do seu nível, a utilização da API é interrompida até ao mês seguinte, a menos que peça um limite superior. Este caso também devolve um 429 rate_limit_error, mas sem o cabeçalho retry-after e com enforced_spend_limit_reached em error.details.error_code. Nenhum ciclo de novas tentativas resolve esse problema. Um limite de despesa inferior definido por si na Console aparece de forma diferente: os pedidos devolvem HTTP 400 invalid_request_error com uma mensagem que começa por You have reached your specified API usage limits, e aumentar ou remover o limite repõe o acesso.

Quatro mecanismos determinam quando o 429 é devolvido.

• Os limites são definidos por classe de modelo. Aplicam-se separadamente a cada modelo, por isso 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, por isso 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 ao mesmo tempo continuam a falhar.
• Na maioria dos modelos, apenas a entrada não colocada em cache conta para o ITPM. input_tokens e cache_creation_input_tokens contam. cache_read_input_tokens não conta na maioria dos modelos Claude, com Claude Haiku 3.5 como exceção documentada. A colocação em cache proporciona, portanto, margem adicional no limite de taxa, além de um desconto. No lado da saída, um max_tokens elevado não conta para o OTPM, porque o OTPM conta apenas os tokens efetivamente produzidos.
• Os limites são definidos 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, e não fica sem limite.

Os níveis Start, Build, Scale e Custom definem os valores efetivos. Estes níveis são atribuídos automaticamente com base no histórico de utilização e na situação da conta. Organizações novas e organizações com pouco histórico de utilização podem começar no nível Evaluation, abaixo dos limites padrão publicados, pelo que o primeiro 429 pode ocorrer antes do previsto numa tabela. Um aumento acentuado da utilização ativa limites de aceleração, que devolvem 429 enquanto ainda está dentro do seu nível. Aumente o tráfego gradualmente. Todos os valores publicados são limites máximos: os limites documentados representam a utilização máxima permitida, não valores mínimos garantidos. Para pedir um limite superior, utilize "Request tier increase" na página Rate limits da Claude Console.

Lendo um 429: retry-after, os cabeçalhos e as tentativas do SDK

Todos os erros da API retornam 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 indica o número de segundos que deve aguardar antes de tentar novamente. As tentativas anteriores a esse intervalo falham. Nem todos os 429 incluem este cabeçalho, e o 429 do limite de gastos nunca o inclui.
• anthropic-ratelimit-requests-limit, anthropic-ratelimit-requests-remaining e anthropic-ratelimit-requests-reset descrevem o orçamento dos seus pedidos.
• anthropic-ratelimit-input-tokens-* e anthropic-ratelimit-output-tokens-* fazem o mesmo para ITPM e OTPM, com os mesmos sufixos para limite, valor restante e reposição.
• anthropic-ratelimit-tokens-* apresenta os valores do limite mais restritivo atualmente em vigor.

Os cabeçalhos de reposição são timestamps RFC 3339. Os cabeçalhos de tokens restantes são arredondados para o milhar mais próximo, por isso devem ser usados como um indicador aproximado. O modo rápido tem o seu próprio pool 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'

Cada resposta também inclui um cabeçalho request-id exclusivo, como req_018EeWyXxfu5pfWkrYcMdjWG. Nos corpos de erro, aparece como request_id; nas respostas dos SDKs Python e TypeScript, aparece como _request_id. Inclua este valor quando contactar o suporte.

Antes de escrever um loop de backoff, confirme se realmente precisa dele. Os SDKs oficiais repetem automaticamente as falhas transitórias, incluindo erros de ligação, limites de taxa e erros de servidor 5xx, usando backoff exponencial, duas vezes por predefinição e respeitando 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.

Consulte os seus próprios limites em vez de uma tabela

Numa subscrição, /usage é o ecrã que importa. Mostra 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. Existem duas ressalvas. O bloco Session mostra a utilização de tokens da 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 de sessões local dessa 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 representa o máximo horário de tokens de entrada não colocados em cache por minuto, comparado com o limite ITPM atual, e mostra a taxa de cache ao lado. Assim, pode monitorizar a aproximação ao limite em vez de só descobrir que o atingiu em produção.

Para consultar os limites configurados de forma programática:

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

São necessárias credenciais da Admin API: uma chave da Admin API, um token OAuth com o âmbito org:admin ou uma chave pessoal ou de conta de serviço que não esteja limitada a um workspace. As chaves da API de workspace não funcionam. GET /v1/organizations/workspaces/{workspace_id}/rate_limits faz o mesmo por workspace. Ambos são somente de leitura: para alterar um limite, utilize a página Rate limits na Console.

Usar menos para ficar sujeito a menos limites

Nos dois sistemas, o consumo é contabilizado da mesma forma internamente. Por isso, estas medidas funcionam em ambos.

• 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 consumo de tokens do Claude Code explica estas medidas em detalhe.
• Reduza o nível de 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 aprofundado não traz benefícios numa renomeação mecânica.
• Reduza a concorrência depois de um 429. Baixe 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.
• Transfira 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, um trabalho noturno deixa de competir com a sua sessão.

Este efeito é mais forte no trabalho que carrega muitos dados para o contexto: se estiver a analisar ações e opções com base em 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 intermitente executado por um programa, e não por uma pessoa, deve usar uma chave de API desde o início. A mudança altera tanto a forma de pagamento como a forma de contabilização, porque a Claude API não tem um nível gratuito. Os planos Max e Team incluem créditos mensais de API para executar as suas próprias aplicações e agentes depois de associar uma organização do Console. Esses créditos não cobrem o Claude Code nem alteram os limites de utilização do seu plano. A sua primeira aplicação da Claude API numa VPS explica a gestão de chaves e as tentativas repetidas. Uma execução longa de um agente continua depois de uma interrupção da ligação quando mantém o Claude Code em execução numa VPS dentro do tmux.

FAQ

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

Porque os limites de sessão e semanais são partilhados por todos os modelos. Essa quota pertence ao plano, não a um modelo. Por isso, /model muda o modelo que responderia, mas não a quota restante. As exceções são os limites por família de modelos: You've hit your Opus limit e You've hit your Sonnet limit aplicam-se apenas a essa família, e o limite do Fable nos planos Max e Premium limita apenas o Fable. Nesses casos, mudar de modelo é a soluçã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 normalmente inclui um cabeçalho retry-after com o número de segundos a aguardar, e as tentativas anteriores falham. Os SDKs oficiais já repetem automaticamente os pedidos após limites de taxa e erros 5xx, com recuo exponencial, duas vezes por predefinição, respeitando esse cabeçalho quando ele está presente. Um erro 429 que ocorre enquanto ainda está dentro dos limites do seu nível indica um limite de aceleração causado por um aumento súbito. Um erro 429 com enforced_spend_limit_reached em error.details.error_code, que nunca inclui um cabeçalho retry-after, é o limite mensal de gastos. Aguardar alguns minutos não o remove.

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. d ou w alterna entre as últimas 24 horas e os últimos 7 dias. Esses valores vêm do histórico local da sessão. Por isso, não incluem o uso de outros dispositivos nem o uso em claude.ai. Na API, a Console apresenta os seus limites de taxa. GET /v1/organizations/rate_limits devolve os limites configurados com credenciais da Admin API, como uma chave da Admin API.

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

Por vezes. Execute /usage-credits para comprar uso adicional além do limite nos planos Pro e Max, ou para o solicitar a um administrador nos planos Team e Enterprise. O comando precisa de um início de sessão em claude.ai através de /login e não está disponível com autenticação por chave da API. Caso contrário, aguarde até ao horário de reposição, use uma reposição gratuita do limite se Settings > Usage em claude.ai ou no Claude Desktop disponibilizar essa opção, mude de modelo se tiver atingido o limite de Opus, Sonnet ou Fable, ou transfira o trabalho para uma chave da API, que contabiliza por minuto em vez de por janela.