Limites de taxa

Existem dois tipos de limites:

1. “Spend limits” (limites de gastos) definem um custo mensal máximo que uma organização pode incorrer pelo uso da API.
2. “Rate limits” (limites de taxa) definem o número máximo de requisições à 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.

Sobre os limites de taxa

• Os limites são projetados para prevenir o abuso da API, minimizando o impacto nos padrões de uso comuns dos clientes.
• Os limites são definidos por “usage tier” (nível de uso). As organizações são colocadas em um nível automaticamente com base no histórico de uso e na situação da conta, e podem passar para um nível mais alto ao longo do tempo à medida que usam a API.
• Novas organizações e organizações com histórico de uso limitado podem começar no nível de avaliação, com limites abaixo dos limites padrão mostrados nesta página enquanto o histórico da conta é estabelecido. Esses limites iniciais fazem parte de como a Anthropic previne fraudes e abusos, e aumentam automaticamente à medida que sua organização constrói um histórico de uso.
• Os limites são definidos no nível da organização. Você pode ver o nível e os limites atuais da sua organização na página Limites de taxa (platform.claude.com/usage/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. Rajadas curtas de requisições podem exceder o limite e acionar erros de limite de taxa.
• Os limites a seguir são os limites padrão para cada nível. Se você precisar de limites mais altos, consulte Solicitando limites mais altos.
• A API usa o algoritmo “token bucket” (balde de tokens) para aplicar limites de taxa. Isso significa que sua capacidade é continuamente reabastecida até o 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 um dos níveis Start, Build e Scale tem um teto de gastos mensal. O teto é o máximo que sua organização pode gastar na API a cada mês do calendário. Você pode ver o teto de gastos mensal da sua organização e definir seu próprio limite em Limites de gastos no Claude Console (platform.claude.com/settings/spend-limits).

As organizações no nível personalizado não têm teto de gastos mensal; os limites são acordados com sua equipe de conta.

Atingindo seu teto de gastos

Quando você atinge o teto de gastos do seu nível, o uso da API é pausado até 00:00 UTC do primeiro dia do mês seguinte, a menos que você solicite um limite mais alto antes disso. Enquanto o uso estiver pausado, as requisições à API retornam HTTP 429:

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "You have reached your API usage limits: your organization has crossed its monthly API usage threshold, set based on your organization's API tier. You will regain access on 2026-09-01 at 00:00 UTC.",
    "details": { "error_code": "enforced_spend_limit_reached" }
  },
  "request_id": "req_018EeWyXxfu5pfWkrYcMdjWG"
}

• O tipo de erro é rate_limit_error, o mesmo de um limite de taxa, mas a resposta não tem o cabeçalho retry-after. Novas tentativas, incluindo as tentativas automáticas do SDK, falham até que o acesso seja retomado.
• Na Messages API, error.details.error_code é enforced_spend_limit_reached. Use-o para diferenciar essa resposta de um limite de taxa.
• Passar para um nível superior restaura o acesso; consulte Solicitando limites mais altos.

Definindo seu próprio limite de gastos

Você também pode definir seu próprio limite de gastos abaixo do teto do seu nível para controlar custos:

1. 1

   Navegue até seus limites de gastos

   Acesse Limites de gastos no Claude Console (platform.claude.com/settings/spend-limits).

2. 2

   Abra o editor de limite de gastos

   Ao lado do Limite de gastos mensal da sua organização, clique em Ajustar limite ou Definir limite.

3. 3

   Ajuste seu limite de gastos

   Insira um novo valor. Seu limite de gastos não pode exceder o teto do seu nível atual.

Quando o uso atinge um limite de gastos que você definiu, as requisições retornam HTTP 400 com o tipo de erro invalid_request_error. A mensagem começa com You have reached your specified API usage limits, ou You have reached your specified workspace API usage limits para um limite de workspace, e informa quando o acesso será retomado. Aumente ou remova o limite para restaurar o acesso mais cedo.

Os limites no workspace do Claude Code são verificados separadamente: requisições do Claude Code acima do limite desse workspace podem, em vez disso, receber um 429 que contém um cabeçalho retry-after.

Limites de taxa

Os limites de taxa da Messages API são medidos em requisições por minuto (RPM), “input tokens per minute” (tokens de entrada por minuto), ou ITPM, e “output tokens per minute” (tokens de saída por minuto), ou OTPM, para cada classe de modelo. Se você exceder qualquer um dos limites de taxa, recebe um erro 429 descrevendo qual limite de taxa foi excedido. Quando a resposta tiver um cabeçalho retry-after, aguarde essa quantidade de segundos antes de tentar novamente.

ITPM com reconhecimento de cache

Os limites de taxa de ITPM padrão da API contam apenas os tokens de entrada fora de cache. Isso torna os limites de taxa efetivamente mais altos do que podem parecer inicialmente.

Os limites de taxa de 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.

Veja 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

Exemplo: Com um limite de 2.000.000 de ITPM e uma “cache hit rate” (taxa de acertos de cache) de 80 por cento, você poderia processar efetivamente 10.000.000 de tokens de entrada totais por minuto (2M fora de cache + 8M em cache), porque os tokens em cache não contam para seu limite de taxa. Esses tokens em cache são cobrados pela taxa de leitura de cache, uma fração do preço base de entrada.

Para obter o maior throughput dentro dos seus limites de taxa, coloque em cache conteúdo repetido, como instruções do sistema e prompts, documentos de contexto grandes, definições de ferramentas e histórico de conversas; consulte cache de prompt para orientações. Com um cache eficaz, você pode aumentar substancialmente seu throughput real sem aumentar seus limites de taxa. Monitore sua taxa de acertos de cache na página Uso no Claude Console para ajustar sua estratégia de cache.

Os limites de taxa de OTPM são avaliados em tempo real à medida que 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 de OTPM, portanto não há desvantagem em termos de limite de taxa ao definir um valor mais alto de max_tokens.

Cada linha nas tabelas a seguir tem seus próprios limites de RPM, ITPM e OTPM. Algumas linhas abrangem vários modelos que compartilham um único limite; consulte as notas que seguem as tabelas. Você pode verificar seus “rate limits” (limites de taxa) atuais e o comportamento deles na página Limites de taxa no Claude Console, ou ler os limites configurados e definir limites de workspace programaticamente com a API de Limites de Taxa.

^{1 O limite de taxa do Fable é um limite total que se aplica ao tráfego combinado do Claude Fable 5.1 e do Claude Fable 5. O Claude Fable 5.2 tem um limite de taxa separado e não faz parte desse bucket combinado. O Claude Mythos 5.2, o Claude Mythos 5.1 e o Claude Mythos 5 compartilham um limite combinado separado.}

^{2 O limite de taxa do Opus é um limite total que se aplica ao tráfego combinado do Claude Opus 4.8, Opus 4.7, Opus 4.6 e Opus 4.5. O Claude Opus 5.5 e o Claude Opus 5 têm, cada um, um limite de taxa separado e não fazem parte desse bucket combinado.}

^{3 O limite de taxa do Sonnet 4.x é um limite total que se aplica ao tráfego combinado do Sonnet 4.6 e do Sonnet 4.5 (descontinuado; consulte Descontinuações de modelos). O Claude Sonnet 5.5 e o Claude Sonnet 5 têm, cada um, um limite de taxa separado e não fazem parte desse bucket combinado.}

Limites de rampa

Um “ramp limit” (limite de rampa) restringe a rapidez com que o uso de tokens da sua organização em um modelo pode crescer. Após um aumento acentuado no uso, as requisições podem retornar um erro 429 mesmo enquanto você estiver abaixo dos seus limites de taxa de ITPM e OTPM. Uma rajada de requisições em poucos segundos também pode contar como um aumento acentuado.

Seu limite de rampa é o maior uso por minuto do modelo pela sua organização no passado recente, mais um incremento. A cada minuto, você pode ir até um incremento acima desse pico, de modo que o limite aumenta à medida que seu uso bem-sucedido cresce. Ele para de aumentar no seu limite de taxa. Após um período de uso menor, o limite de rampa volta a diminuir. O limite nunca cai abaixo de uma quantidade inicial, mesmo que você não tenha usado o modelo recentemente.

• Os limites de rampa podem se aplicar a qualquer modelo.
• Os tokens de entrada e os tokens de saída são contados separadamente.
• O uso do modo rápido tem seus próprios limites de rampa, separados do uso padrão do mesmo modelo.
• Assim como no ITPM com reconhecimento de cache, os tokens lidos do cache não contam para um limite de rampa. Os tokens de entrada fora de cache e os tokens gravados no cache contam.
• O incremento e a quantidade inicial variam de acordo com o modelo e podem mudar. A mensagem de erro geralmente informa seu limite de rampa atual, o incremento e seu limite de taxa.
• O tipo de erro é rate_limit_error, o mesmo de um limite de taxa. Na Messages API, error.details.error_code é ramp_limit_exceeded. Use-o para diferenciar essa resposta de um limite de taxa.
• A Message Batches API não está sujeita a limites de rampa.

Se você receber um 429 de um limite de rampa:

• Aguarde pelo menos o número de segundos indicado no cabeçalho retry-after antes de tentar novamente.
• Mantenha seu tráfego em um nível em que as requisições sejam bem-sucedidas e, em seguida, aumente-o em no máximo um incremento por minuto.
• Inicie tarefas agendadas ou em massa a uma taxa baixa e distribua as requisições uniformemente, em vez de enviar tudo de uma vez.

Message Batches API

A Message Batches API tem seu próprio conjunto de limites de taxa, que são compartilhados entre todos os modelos. Eles incluem um limite de requisições por minuto (RPM) para todos os endpoints da API e um limite no número de requisições em lote que podem estar na fila de processamento ao mesmo tempo. Uma “requisição em lote” aqui se refere a uma parte de um lote de mensagens. Você pode criar um lote de mensagens contendo milhares de requisições em lote, cada uma das quais conta para esse limite. Uma requisição em lote permanece na fila de processamento até que o modelo a processe com sucesso.

Managed Agents

Os endpoints do Claude Managed Agents têm limites de taxa por organização. Esses limites são separados dos limites de taxa da Messages API descritos anteriormente nesta página.

Files API

As requisições da Files API têm seu próprio limite por organização, compartilhado entre as operações de upload, listagem, recuperação, download e exclusão, e separado dos limites da Messages API descritos anteriormente nesta página. Consulte Limites de taxa da Files API para o valor atual.

Limites de taxa do modo rápido

Ao usar o modo rápido com speed: "fast", aplicam-se limites de taxa dedicados, separados dos limites de taxa padrão. Eles se aplicam ao Claude Fable 5.2, Claude Mythos 5.2, Claude Opus 5.5, Claude Opus 5 e Claude Opus 4.8. O modo rápido está em prévia de pesquisa para o Claude Opus 5 e descontinuado para o Claude Opus 4.8.

O Claude Fable 5.2, o Claude Mythos 5.2 e o Claude Opus 5.5 têm um limite de taxa padrão do modo rápido. O limite padrão se aplica nos níveis Start, Build e Scale. Você não precisa solicitar acesso ao modo rápido para esses modelos. Organizações no nível de avaliação podem usar o modo rápido com esses modelos assim que passarem para o nível Start, Build ou Scale.

Para ver seus limites de taxa do modo rápido, acesse a página Limites de taxa no Claude Console. Quando você excede seus limites de taxa do modo rápido, 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 Limites de taxa do modo rápido para detalhes sobre esses cabeçalhos.

Monitorando seus limites de taxa no Console

Você pode monitorar o uso dos seus limites de taxa na página Uso do Claude Console.

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

• O gráfico Rate Limit - Input Tokens inclui:
  • Máximo por hora de tokens de entrada não em cache por minuto
  • Seu limite de taxa atual de tokens de entrada por minuto
  • A taxa de cache dos 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 por hora de tokens de saída por minuto
  • Seu limite de taxa atual de tokens de saída por minuto

Solicitando limites mais altos

Para solicitar limites de taxa mais altos ou um teto de gastos mensal mais alto, use Solicitar aumento de nível na página Limites de taxa no Claude Console. O suporte da Anthropic também pode aumentar os limites; para necessidades urgentes, entre em contato com o suporte da Anthropic.

Definindo limites mais baixos para workspaces

Para saber mais sobre workspaces, consulte Workspaces.

Para proteger os workspaces da sua organização contra possível uso excessivo, você pode definir limites personalizados de gastos e de taxa para cada workspace.

Exemplo: se o limite da sua organização for 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 contra possível uso excessivo e distribui os recursos de forma mais equilibrada em toda a sua organização. Os outros 10.000 tokens de entrada por minuto, mais qualquer parte dos 30.000 que esse workspace não usar, permanecem disponíveis para outros workspaces.

Observação:

• Você não pode definir limites de gastos no workspace padrão.
• Se não forem definidos, os limites do workspace correspondem ao limite da organização.
• Os limites de workspace são definidos para cada 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 a soma dos limites dos workspaces seja maior.

Para ler os limites de taxa atuais da sua organização e do seu workspace ou definir limites de taxa de workspace programaticamente, use a API de Limites de Taxa.

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 é redefinido.

Os seguintes cabeçalhos são retornados:

Os cabeçalhos anthropic-ratelimit-tokens-* exibem os valores do limite mais restritivo atualmente em vigor. Por exemplo, se você excedeu o limite de tokens por minuto do workspace, os cabeçalhos contêm os valores do limite de taxa de tokens por minuto do workspace. Se os limites de workspace não se aplicarem, os cabeçalhos retornam o total de tokens restantes, onde o total é a soma dos tokens de entrada e de saída. Para ver em qual workspace uma requisição foi contabilizada, leia o cabeçalho de resposta anthropic-workspace-id, que contém o ID do workspace para o qual sua chave de API ou token de acesso foi resolvido.