Limites de taxa

Existem dois tipos de limites:

1. Limites de gastos definem um custo mensal máximo que uma organização pode incorrer pelo uso da API.
2. Limites de taxa definem o número máximo de requisições de API que uma organização pode fazer em um período de tempo definido.

A API aplica limites configurados pelo serviço no nível da organização, mas você também pode definir limites configuráveis pelo usuário para os workspaces da sua organização.

Esses limites se aplicam tanto ao uso do Standard Tier quanto do Priority Tier. Para mais informações sobre o Priority Tier, que oferece níveis de serviço aprimorados em troca de gastos comprometidos, consulte Service Tiers.

Sobre os limites de taxa

• Os limites são projetados para prevenir abuso da API, minimizando o impacto nos padrões comuns de uso dos clientes.
• Os limites são definidos por tier de uso, onde cada tier está associado a um conjunto diferente de limites de gastos e de taxa.
• Sua organização avançará de tier automaticamente conforme você atingir certos limiares ao usar a API. Os limites são definidos no nível da organização. Você pode ver os limites da sua organização na página Limits no Claude Console.
• Você pode atingir limites de taxa em intervalos de tempo mais curtos. Por exemplo, uma taxa de 60 requisições por minuto (RPM) pode ser aplicada como 1 requisição por segundo. Picos curtos de requisições podem exceder o limite e acionar erros de limite de taxa.
• Os limites descritos abaixo são os limites padrão de tier. Se você está buscando limites mais altos e personalizados ou o Priority Tier para níveis de serviço aprimorados, entre em contato com vendas na página Limits.
• A API usa o algoritmo token bucket para fazer a limitação de taxa. Isso significa que sua capacidade é continuamente reabastecida até seu limite máximo, em vez de ser redefinida em intervalos fixos.
• Todos os limites descritos aqui representam o uso máximo permitido, não mínimos garantidos. Esses limites têm como objetivo reduzir gastos excessivos não intencionais e garantir uma distribuição justa de recursos entre os usuários.

Limites de gastos

Cada tier de uso tem um limite de quanto você pode gastar na API a cada mês do calendário. Uma vez que você atinja o limite de gastos do seu tier, até que você se qualifique para o próximo tier, você terá que esperar até o próximo mês para poder usar a API novamente.

Para se qualificar para o próximo tier, você deve atender a um requisito de depósito. Para minimizar o risco de financiar excessivamente sua conta, você não pode depositar mais do que seu limite de gastos mensal.

Requisitos para avançar de tier

Aumentando seus limites de gastos

Sua organização tem dois tipos de limites de gastos: um limite definido pelo cliente que você controla diretamente, e um teto imposto pelo tier definido pelo seu tier de uso. Cada um tem um processo diferente para ser aumentado.

Limites de gastos definidos pelo cliente

Você pode definir um limite de gastos menor que o teto do seu tier para controlar custos. Para ajustá-lo:

Limites de gastos impostos pelo tier

Quando você precisar de um limite maior que o teto do seu tier (o teto do Tier 4 é $200.000 por mês), clique em Contact Sales na página Limits. Isso abre o formulário de contato em uma nova aba, e um membro da equipe de vendas entrará em contato por e-mail quando sua organização for atualizada.

O Monthly Invoicing remove completamente o teto de gastos mensal e usa termos de pagamento Net-30 por padrão.

Limites de taxa

Os limites de taxa para a Messages API são medidos em requisições por minuto (RPM), tokens de entrada por minuto (ITPM) e tokens de saída por minuto (OTPM) para cada classe de modelo. Se você exceder qualquer um dos limites de taxa, receberá um erro 429 descrevendo qual limite de taxa foi excedido, junto com um cabeçalho retry-after indicando quanto tempo esperar.

ITPM com reconhecimento de cache

Muitos provedores de API usam um limite combinado de "tokens por minuto" (TPM) que pode incluir todos os tokens, tanto em cache quanto não em cache, de entrada e de saída. Para a maioria dos modelos Claude, apenas tokens de entrada não armazenados em cache contam para seus limites de taxa ITPM. Esta é uma vantagem importante que torna os limites de taxa efetivamente mais altos do que podem parecer inicialmente.

Os limites de taxa ITPM são estimados no início de cada requisição, e a estimativa é ajustada durante a requisição para refletir o número real de tokens de entrada usados.

Aqui está o que conta para o ITPM:

• input_tokens (tokens após o último ponto de interrupção de cache) ✓ Contam para o ITPM
• cache_creation_input_tokens (tokens sendo gravados no cache) ✓ Contam para o ITPM
• cache_read_input_tokens (tokens lidos do cache) ✗ NÃO contam para o ITPM na maioria dos modelos

total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens

Exemplo: Com um limite de 2.000.000 ITPM e uma taxa de acerto de cache de 80%, você poderia efetivamente processar 10.000.000 de tokens de entrada totais por minuto (2M não em cache + 8M em cache), porque tokens em cache não contam para seu limite de taxa.

Os limites de taxa OTPM são avaliados em tempo real conforme os tokens de saída são produzidos, contando apenas os tokens realmente gerados. O parâmetro max_tokens não é considerado nos cálculos de limite de taxa OTPM, portanto não há desvantagem de limite de taxa em definir um valor mais alto para max_tokens.

Os limites de taxa são aplicados separadamente para cada modelo; portanto, você pode usar diferentes modelos até seus respectivos limites simultaneamente. Você pode verificar seus limites de taxa atuais e comportamento no Claude Console, ou ler os limites configurados programaticamente com a Rate Limits API.

^{* - O limite de taxa do Opus é um limite total que se aplica ao tráfego combinado entre Claude Opus 4.8, Opus 4.7, Opus 4.6, Opus 4.5, Opus 4.1 (obsoleto) e Opus 4 (obsoleto).}

^{** - O limite de taxa do Sonnet 4.x é um limite total que se aplica ao tráfego combinado entre Sonnet 4.6, Sonnet 4.5 e Sonnet 4 (obsoleto).}

^{† - O limite conta cache_read_input_tokens para o uso de ITPM.}

Message Batches API

A Message Batches API tem seu próprio conjunto de limites de taxa que são compartilhados entre todos os modelos. Estes incluem um limite de requisições por minuto (RPM) para todos os endpoints da API e um limite no número de requisições de batch que podem estar na fila de processamento ao mesmo tempo. Uma "requisição de batch" aqui se refere a parte de um Message Batch. Você pode criar um Message Batch contendo milhares de requisições de batch, cada uma das quais conta para este limite. Uma requisição de batch é considerada parte da fila de processamento quando ainda não foi processada com sucesso pelo modelo.

Managed Agents

Os endpoints de Claude Managed Agents têm limites de taxa por organização. Esses limites são separados dos limites de taxa da Messages API acima.

Limites de taxa do modo rápido

Ao usar o modo rápido (prévia de pesquisa) com speed: "fast" no Claude Opus 4.8, Opus 4.7 ou Opus 4.6, aplicam-se limites de taxa dedicados que são separados dos limites de taxa padrão do Opus. Quando os limites de taxa do modo rápido são excedidos, a API retorna um erro 429 com um cabeçalho retry-after.

A resposta inclui cabeçalhos anthropic-fast-* que indicam o status do seu limite de taxa do modo rápido. Consulte Modo rápido para detalhes sobre esses cabeçalhos.

Monitorando seus limites de taxa no Console

Você pode monitorar seu uso de limite de taxa na página Usage do Claude Console.

Além de fornecer gráficos de tokens e requisições, a página Usage fornece dois gráficos separados de limite de taxa. Use esses gráficos para ver quanta margem você tem para crescer, quando você pode estar atingindo o pico de uso, entender melhor quais limites de taxa solicitar, ou como você pode melhorar suas taxas de cache. Os gráficos visualizam várias métricas para um determinado limite de taxa (por exemplo, por modelo):

• O gráfico Rate Limit - Input Tokens inclui:
  • Máximo horário de tokens de entrada não armazenados em cache por minuto
  • Seu limite de taxa atual de tokens de entrada por minuto
  • A taxa de cache para seus tokens de entrada (ou seja, a porcentagem de tokens de entrada lidos do cache)
• O gráfico Rate Limit - Output Tokens inclui:
  • Máximo horário de tokens de saída por minuto
  • Seu limite de taxa atual de tokens de saída por minuto

Definindo limites mais baixos para Workspaces

Para mais informações sobre workspaces, consulte Workspaces.

Para proteger Workspaces na sua Organização de possível uso excessivo, você pode definir limites personalizados de gastos e de taxa por Workspace.

Exemplo: Se o limite da sua Organização é de 40.000 tokens de entrada por minuto e 8.000 tokens de saída por minuto, você pode limitar um Workspace a 30.000 tokens de entrada por minuto. Isso protege outros Workspaces de possível uso excessivo e garante uma distribuição mais equitativa de recursos em toda a sua Organização. Os tokens por minuto restantes não utilizados (ou mais, se aquele Workspace não usar o limite) ficam então disponíveis para outros Workspaces usarem.

Observação:

• Você não pode definir limites no Workspace padrão.
• Se não definidos, os limites do Workspace correspondem ao limite da Organização.
• Os limites de Workspace são definidos por tipo de limitador (como requisições por minuto, tokens de entrada por minuto ou tokens de saída por minuto).
• Os limites de toda a Organização sempre se aplicam, mesmo que os limites de Workspace somem mais.

Para ler seus limites de taxa atuais de organização e workspace programaticamente, use a Rate Limits API.

Cabeçalhos de resposta

A resposta da API inclui cabeçalhos que mostram o limite de taxa aplicado, o uso atual e quando o limite será redefinido.

Os seguintes cabeçalhos são retornados:

Os cabeçalhos anthropic-ratelimit-tokens-* exibem os valores para o limite mais restritivo atualmente em vigor. Por exemplo, se você excedeu o limite de tokens por minuto do Workspace, os cabeçalhos conterão os valores de limite de taxa de tokens por minuto do Workspace. Se os limites de Workspace não se aplicarem, os cabeçalhos retornarão o total de tokens restantes, onde o total é a soma de tokens de entrada e saída. Essa abordagem garante que você tenha visibilidade sobre a restrição mais relevante no seu uso atual da API.