Claude API 429 rate_limit_error — causas e a correção que funciona

Um 429 da Claude API significa que você ultrapassou um dos limites por minuto da Anthropic — solicitações, tokens de entrada ou tokens de saída. A correção raramente é “esperar mais”: é respeitar retry-after, adicionar backoff com jitter e suavizar os picos. Este é o guia completo.

O erro

response (HTTP 429)

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "Number of request tokens has exceeded your per-minute rate limit"
  }
}

Causas e soluções em resumo

Causa	Solução
Limite de solicitações por minuto (RPM) atingido	Enfileire as solicitações no cliente; respeite o cabeçalho retry-after antes de tentar novamente.
Limite de tokens de entrada por minuto (ITPM) atingido — prompts grandes, poucas solicitações	Reduza o contexto recuperado e habilite o prompt caching para que os tokens armazenados em cache deixem de contar contra você nos planos compatíveis.
Limite de tokens de saída por minuto (OTPM) atingido	Defina max_tokens de forma realista — o OTPM costuma ser o primeiro limite para gerações longas.
Tráfego em pico (o cron dispara tudo em :00)	Adicione jitter aos agendamentos; distribua os trabalhos em lote ao longo do minuto.

Leia a resposta antes de tentar novamente

A Anthropic retorna um cabeçalho retry-after com o número de segundos a esperar, e a mensagem de erro informa qual limite foi ultrapassado. Tentar novamente instantaneamente sem lê-lo é como um único 429 se transforma em uma tempestade de 429s.

Adicione backoff exponencial com jitter

Tente novamente apenas em status que podem ser repetidos (429, 500, 529); nunca em erros de autenticação ou validação. Este trecho funciona sem alterações diretamente com a Anthropic ou com qualquer endpoint compatível com OpenAI:

backoff.py

import time, random
from openai import OpenAI, APIStatusError

client = OpenAI(base_url="https://api.kunavo.com/v1", api_key="sk-kn-...")

def with_backoff(fn, max_retries=5):
    for attempt in range(max_retries):
        try:
            return fn()
        except APIStatusError as e:
            if e.status_code not in (429, 500, 529):
                raise                      # don't retry auth/validation errors
            retry_after = e.response.headers.get("retry-after")
            delay = float(retry_after) if retry_after else min(2 ** attempt, 30)
            time.sleep(delay + random.uniform(0, 0.5))   # jitter avoids herds
    raise RuntimeError("retries exhausted")

resp = with_backoff(lambda: client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "ping"}],
    max_tokens=32,
))
print(resp.choices[0].message.content)

Reduza os tokens, não apenas as solicitações

Se a mensagem indicar limites de tokens, apenas o backoff não resolverá. Reduza os trechos recuperados, limite max_tokens e ative o prompt caching — um prompt de sistema grande e estável, com 10% da taxa de entrada, também alivia a pressão sobre o ITPM.

Se você estiver chamando pela Kunavo

Chamar o Claude pelo Kunavo não remove magicamente os limites de taxa, mas muda a economia das falhas: solicitações que falham (incluindo 429s) nunca são cobradas, e o painel de uso por chave mostra exatamente qual chave e modelo estão gerando o pico, para que você possa suavizá-lo. O mesmo trecho de backoff acima funciona sem alterações — apenas a base_url é diferente. Os limites de taxa são um teto de throughput, não um preço — para saber quanto uma chamada ao Claude realmente custa por 1 milhão de tokens, com a tabela oficial da Anthropic ao lado da nossa, consulte tabela de preços da Claude API da Anthropic.

Perguntas frequentes

Fazer upgrade do meu nível da Anthropic remove os 429s?

Níveis superiores aumentam os tetos por minuto, então os 429s se tornam menos frequentes, mas qualquer teto fixo pode ser atingido por um pico. O código de produção precisa de backoff independentemente do nível.

Devo tentar novamente um 429 imediatamente?

Não — respeite o cabeçalho retry-after (ou use backoff exponencial com jitter se ele estiver ausente). Tentativas imediatas prolongam a janela limitada e podem evoluir para um bloqueio mais longo.

Solicitações 429 que falharam custam dinheiro?

A Anthropic não cobra por solicitações rejeitadas, e o Kunavo também não — solicitações que falham nunca são cobradas. O custo de um 429 é latência, não dinheiro.

Guias relacionados

Mais detalhes sobre o significado dos erros estão em referência de erros; obter uma chave leva um minuto por meio de cadastro e da guia de autenticação.