Erro 429 rate_limit_error na API da Claude — o que significa e como resolver

429 é o erro que diz "mais devagar", não "você está sem dinheiro". A diferença importa: a correção de um é esperar, a do outro é recarregar — e confundir os dois leva a horas de depuração no lugar errado.

O erro

resposta (HTTP 429)

{
  "type": "error",
  "error": { "type": "rate_limit_error",
             "message": "Number of requests has exceeded your rate limit" }
}

Causas e correções em resumo

Causa	Correção
Requisições por minuto acima do limite da sua conta	Enfileire e limite a concorrência no cliente, em vez de disparar tudo de uma vez.
Tokens por minuto acima do limite	Prompts longos consomem a cota de tokens muito antes da cota de requisições. Reduza o contexto ou divida o trabalho.
Vários processos usando a mesma chave	O limite é da chave, não do processo. Workers paralelos somam contra a mesma cota.
Retry sem backoff	Repetir na hora mantém você permanentemente acima do limite. Backoff exponencial com jitter é obrigatório.

Respeite o retry-after quando ele vier

Quando a resposta traz o cabeçalho retry-after, ele não é sugestão: é o tempo exato após o qual a requisição volta a ser aceita. Esperar menos garante outro 429.

retry_after.py

import time
from openai import APIStatusError

try:
    resp = client.chat.completions.create(model=MODELO, messages=msgs)
except APIStatusError as e:
    if e.status_code == 429:
        espera = float(e.response.headers.get("retry-after", 5))
        time.sleep(espera)
        resp = client.chat.completions.create(model=MODELO, messages=msgs)
    else:
        raise

Limite a concorrência na origem

A causa mais comum não é o volume total e sim a rajada: vinte requisições disparadas no mesmo instante estouram o limite que sessenta requisições espalhadas em um minuto não estouram. Um semáforo resolve o que o retry sozinho não resolve.

concorrencia.py

import asyncio

LIMITE = asyncio.Semaphore(4)   # no máximo 4 chamadas simultâneas

async def chamar(msgs):
    async with LIMITE:
        return await client.chat.completions.create(
            model=MODELO, messages=msgs)

Confirme que é limite, e não saldo

Um 429 nunca significa falta de créditos — isso é 402. Se o seu log mistura os dois, separe por status antes de investigar: a correção do 429 é temporização, a do 402 é recarga. Repetir um 402 falha para sempre.

Se você chama pela Kunavo

Na Kunavo os limites são por chave e o saldo é uma carteira pré-paga separada, então os dois casos aparecem com status diferentes: 429 para limite de taxa e 402 quando o saldo não cobre a chamada — nunca um disfarçado de outro. Requisições recusadas não são cobradas. As tarifas por token, que determinam quanto cada chamada consome do saldo, estão em nosso guia de preços da API da Claude.

Perguntas frequentes

429 significa que acabaram meus créditos?

Não. Falta de saldo é 402. O 429 é sobre velocidade: você mandou requisições ou tokens demais em pouco tempo, e esperar resolve.

Quanto tempo devo esperar?

Se vier o cabeçalho retry-after, exatamente esse tempo. Sem ele, backoff exponencial a partir de 1–2 segundos com jitter, até um teto de 30–60 segundos.

Aumentar o limite resolve?

Ajuda se o volume for realmente alto, mas a maioria dos 429 vem de rajadas curtas. Limitar a concorrência costuma resolver sem mudar limite nenhum.

Guias relacionados

A semântica completa dos erros está na referência de erros; para obter uma chave, basta criar uma conta e seguir a documentação de autenticação.