Limites de taxa no Claude Code: assinatura versus API 429

O que um rate limit significa no Claude Code

O Claude Code oferece dois modos de autenticação fundamentalmente distintos:

• Assinatura (Pro, Max, Team ou Enterprise): login por OAuth do Claude.ai. Claude Code e outras superfícies do Claude consomem o pool compartilhado do plano; veja janelas atuais e restrições adicionais em /usage e nas configurações da conta.
• Chave de API (ANTHROPIC_API_KEY no ambiente): as requisições vão diretamente para api.anthropic.com. Os limites são RPM, ITPM e OTPM do tier do seu workspace no Anthropic Console.

Se ANTHROPIC_API_KEY estiver definido, ele tem precedência sobre a assinatura. O Claude Code passa a usar a chave mesmo que você tenha feito login pela assinatura — uma causa comum de confusão.

Precisa saber se a requisição chegou a um endpoint de terceiros? O BetterToken acrescenta uma camada de diagnóstico: o Dashboard mostra status da requisição, modelo, tokens de entrada, saída e cache, além da cobrança correspondente. Isso ajuda a separar um limite do provedor de um erro da API Anthropic. Consulte a documentação do BetterToken para configurar Base URL e chave de API, e confira a configuração contra seu workflow atual.

Como identificar limite de assinatura, Anthropic API ou outro endpoint

Comece executando /status no Claude Code. Ele mostra o método de autenticação atual — conta com assinatura ou chave de API — e define onde investigar em seguida.

• Assinatura Pro/Max/Team: /status mostra subscription e a mensagem menciona limite de sessão ou semanal, com horário de reset. O uso do plano se esgotou; aguarde o reset e confira /usage e, se disponível, /usage-credits.
• Anthropic API 429: /status mostra uma chave de API, ANTHROPIC_API_KEY existe no ambiente e a resposta contém HTTP 429 ou rate_limit_error. RPM, ITPM ou OTPM do tier selecionado estão restritos. Verifique primeiro retry-after e reduza a concorrência.
• Endpoint de terceiros: há Base URL personalizada e chave do provedor; código e formato da resposta podem ser diferentes dos da Anthropic. Leia primeiro a resposta e depois a status page e os termos de cota do provedor.

Trate 500 api_error, 504 timeout_error e 529 overloaded_error separadamente. São erros de servidor ou transitórios, não prova de que a franquia da assinatura acabou. Use exponential backoff limitado. Cada resposta da Anthropic traz request-id em um cabeçalho; erros também incluem request_id no JSON. Guarde esse identificador para o suporte.

Diagnóstico passo a passo sem vazar a chave de API

Passo 1. Verifique o método de autenticação

Em uma sessão do Claude Code:

/status

Veja “Login method” ou “Auth token”. Se ANTHROPIC_API_KEY estiver definido, mas você quiser usar a assinatura, remova antes a variável:

unset ANTHROPIC_API_KEY

Reinicie o Claude Code e confira /status novamente.

Passo 2. Leia a mensagem de erro completa

O texto exato é o principal sinal: “Resets at [horário]” significa limite da assinatura; rate_limit_error com cabeçalho retry-after é API 429 e pede consulta ao Anthropic Console; api_error, timeout_error e overloaded_error são falhas transitórias 5xx/529 para repetir com backoff; formato específico do provedor com Base URL não padrão aponta para problema no provedor.

Guarde um conjunto de diagnóstico seguro: horário, error.type, request-id/request_id, versão do Claude Code e endpoint selecionado. Não inclua chave de API, cabeçalho Authorization nem conteúdo de .env.

Passo 3. Confira o uso atual

Para a assinatura:

/usage

Ele mostra as barras de uso de Pro/Max: o restante até o reset da janela de cinco horas e até o teto semanal. Trocar de modelo com /model não recupera horas de computação já consumidas; a franquia é compartilhada entre modelos.

Para a API, abra Anthropic Console → Settings → Limits. Lá estão tier, limites atuais de RPM/ITPM/OTPM e uso. No BetterToken, abra o Dashboard e encontre a requisição pelo horário. Você pode verificar modelo, status, tokens de entrada/saída/cache e cobrança. O Dashboard mostra se a requisição chegou ao BetterToken, mas o identificador do corpo ou dos cabeçalhos deve ser guardado separadamente.

Passo 4. Confira o status oficial

https://status.anthropic.com/

Um incidente que afete Claude Code ou a API explica o problema independentemente dos seus limites.

Passo 5. Procure conflitos de configuração

Definir ANTHROPIC_API_KEY e ANTHROPIC_BASE_URL ao mesmo tempo pode causar comportamento inesperado. Não mantenha dois conjuntos de variáveis para esquemas de autenticação diferentes no mesmo ambiente. Ao pedir ajuda, nunca envie Authorization, x-api-key ou .env em logs e capturas. Texto do erro, código HTTP, claude --version e /status sem valores de chave são suficientes.

O que fazer depois de identificar a origem

Limite da assinatura (Pro/Max/Team): aguarde o reset exibido em /usage e na mensagem. Se o aviso for de um modelo específico, escolha um modelo disponível com /model; isso não restaura o uso geral do plano. Se houver usage credits, execute /usage-credits e confira as configurações. Entre tarefas sem relação, use /clear para resetar o contexto e diminuir o consumo de requisições posteriores.

Anthropic API 429 (rate_limit_error): leia retry-after e espere o período indicado. Reduza a concorrência, pois tarefas paralelas de agentes consomem RPM, ITPM e OTPM mais rápido. Confira o tier e os limites atuais em Anthropic Console → Settings → Limits, em vez de números fixos antigos. Para aumento duradouro, solicite limites maiores à Anthropic pelo Console.

Endpoint de terceiros: abra a status page, peça ao provedor a cota atual e o formato de erro e, se necessário, mude para a API Anthropic direta ou outro provedor.

5xx / 529: use exponential backoff limitado para 500, 504 e 529; o SDK oficial já repete alguns erros transitórios. Verifique status.anthropic.com; se o erro persistir, envie ao suporte request-id, horário e tipo do erro, sem segredos.

Quando esperar, alterar a carga ou contatar o suporte

• Limite de assinatura com hora de reset: espere, troque o modelo ou use /clear.
• API 429 com retry-after: espere o período indicado e reduza a concorrência.
• API 429 frequente sem retry-after: confira o tier e peça limite maior se necessário.
• 500 / 504 / 529: aplique backoff limitado, confira o status do serviço e guarde request-id.
• Erro de endpoint de terceiros: contate o respectivo provedor.
• Limite incerto com assinatura ativa: contate o suporte Claude.ai.
• Limite incerto com chave de API ativa: contate o suporte Anthropic Console.

O suporte de assinatura e o suporte de API são equipes separadas. A equipe do Anthropic API Console não resolve limite de assinatura Pro/Max, e vice-versa.

FAQ

Por que vejo “rate limit” logo ao iniciar uma sessão?

As causas possíveis são: (1) o ambiente contém uma ANTHROPIC_API_KEY de tier baixo, que tem precedência sobre a assinatura — confirme com /status; (2) uma sessão anterior consumiu grande parte da janela móvel, que não é resetada ao reiniciar o Claude Code; (3) vários dispositivos ou tarefas de agentes usam a mesma conta e o uso é somado.

Trocar de modelo com /model ajuda?

Em parte para assinaturas. “You've hit your Opus limit” significa que a franquia de Opus acabou; mudar para Sonnet pode permitir continuar na mesma sessão. O orçamento compartilhado de computação semanal e de cinco horas não é restaurado pela troca de modelo.

Devo enviar logs completos ao pedir ajuda?

Não. Texto completo do erro, código HTTP, /status sem valores de chave, claude --version, horário e o estado de status.anthropic.com naquele momento bastam.

Quais limites dinâmicos mudam mais frequentemente?

Os limites de tier da API (RPM, ITPM e OTPM) e os parâmetros das janelas de assinatura podem mudar. Obtenha valores atuais apenas nas páginas oficiais:

• Custos e uso: code.claude.com/docs/en/costs
• Erros e limites de taxa da API: platform.claude.com/docs/en/api/errors
• Status do serviço: status.anthropic.com

Não confie em números de tutoriais ou fóruns: eles ficam desatualizados rapidamente.