Erro 429 no Claude Code: por que acontece e como resolver

O 429 é o código HTTP de too many requests. Ele não significa que sua chave está errada nem que a ferramenta quebrou: significa que você pediu mais do que a janela de uso permitia naquele momento.

Existem duas causas bem diferentes, e a saída é diferente em cada uma: ou a sua cota acabou dentro da janela, ou a capacidade compartilhada do provedor está saturada naquele instante.

Como ele aparece na tela

No terminal, o Claude Code costuma mostrar alguma variação de:

• 429 Too Many Requests
• rate_limit_error
• usage limit reached com um horário de retomada
• All credentials for model X are cooling down, quando quem responde é um gateway

As duas primeiras são genéricas. A terceira já diz que é a sua cota. A quarta diz que o problema não é seu: é a fila do outro lado.

Com que frequência isso acontece, de verdade

Números do nosso gateway, janela de 7 dias, 145.013 tentativas de roteamento:

Duas leituras importam aqui. A primeira: o 429 é comum e quase sempre transitório — 2,7% das tentativas, não 2,7% das suas conversas, porque uma tentativa que volta 429 costuma ser repetida automaticamente em outra rota antes de você ver qualquer coisa.

A segunda: quando o limite é real e não há para onde desviar, a espera na fila passa de três minutos. É por isso que às vezes parece que a ferramenta travou — ela está esperando a janela virar.

O que fazer, em ordem

1. Espere a janela virar. Se a mensagem trouxe um horário, ele é literal. Cota não se recupera aos poucos: ela volta de uma vez quando a janela reseta.
2. Reduza o que sobe. É o que mais funciona e quase ninguém faz. A requisição típica do Claude Code envia dezenas de milhares de tokens de contexto — veja quantos tokens ele consome de verdade. Menos arquivos abertos e sessão nova a cada assunto novo derrubam o consumo mais que qualquer ajuste de configuração.
3. Troque de modelo para a tarefa. Modelos maiores consomem cota mais rápido. Tarefa simples em modelo grande é cota queimada à toa.
4. Confira se é 429 mesmo. Erro de configuração de endereço base costuma voltar 401, não 429. Se você está vendo 401, o problema é outro — veja a página de configuração.

Erros comuns

• Tentar de novo imediatamente. Repetir dentro da janela fechada não devolve acesso e ainda consome tentativa.
• Trocar a chave achando que ela queimou. 429 não é problema de chave. Chave inválida devolve 401.
• Achar que resposta curta gasta pouco. A cota é consumida na subida, antes de a IA escrever a primeira palavra.
• Confundir o 429 do log com o 429 na sua tela. Em gateway com múltiplas rotas, a maioria dos 429 registrados é absorvida por uma nova tentativa e nunca chega ao usuário.

Como medimos

Fonte: o histórico de uso do nosso próprio gateway, janela de 7 dias encerrada em 9 de setembro de 2026, 145.013 tentativas de roteamento. Cada linha contada é uma tentativa de rota, não uma requisição do usuário — a distinção importa e está explicada acima. Latências são médias das tentativas que terminaram no código correspondente. Nenhum dado identificável de cliente entra nestes números.

Perguntas frequentes

429 é o mesmo que ter estourado o plano?
Nem sempre. Pode ser a sua cota dentro da janela, e pode ser saturação momentânea do lado do provedor. A mensagem com horário de retomada indica cota; a genérica, não.

Quanto tempo preciso esperar?
Se a mensagem trouxe horário, até ele. Sem horário, a janela costuma ser de poucas horas. Quando a espera vem de fila de capacidade, ela é bem mais curta — na nossa medição, cerca de três minutos no pior caso.

Trocar de chave resolve?
Não. Chave inválida devolve 401, não 429. Se você vê 429, a chave está funcionando.

Dá para evitar o 429 sem gastar mais?
Na maior parte dos casos, sim: controlando o contexto que sobe a cada mensagem. É o fator que mais pesa e o único totalmente sob o seu controle.

No CodeJato eu vou bater em 429?
Pode acontecer, como em qualquer serviço com capacidade finita — nós publicamos a frequência real acima em vez de prometer que nunca ocorre. A diferença é que a mensalidade é fixa em reais e não há cobrança por token. Ver os planos.