1) Confirme que é rate limit (e não credencial/bug)
Cheque o status 429 e os headers de limite (quando existirem), além do corpo do erro. Alguns serviços retornam mensagens como "Too Many Requests" ou informam quando tentar de novo. Se o 429 vier intercalado com 401/403, pode ser token expirando ou permissão inconsistente, não só volume.
2) Identifique o “padrão de pico” do seu fluxo
Mapeie onde o volume explode: loop em lista grande, disparo por webhook em horário de campanha, importação inicial, ou paralelismo sem controle. O problema quase sempre é um burst (rajada) curto, não a média do dia.
3) Leia (ou infira) o limite da API
Quando a documentação/headers não forem claros, faça um teste controlado: aumente chamadas gradualmente e observe quando o 429 aparece. Você não precisa de número exato; precisa de um “teto seguro” para operar. Registre também se o limite é por IP, por token, por conta ou por endpoint.
4) Reduza concorrência e serialize onde dói
Muitos 429 vêm de tarefas paralelas. Limite quantas execuções rodam ao mesmo tempo, principalmente em etapas que chamam a mesma API. Em vez de 50 itens em paralelo, processe em lotes pequenos ou um-por-um com atraso curto.
5) Aplique retry com backoff + jitter (do jeito certo)
Retry não é “tenta de novo em 1 segundo pra sempre”. Use backoff exponencial (1s, 2s, 4s, 8s...) com jitter (aleatoriedade) para evitar que todo mundo re-tente junto. Respeite o header Retry-After se a API mandar. Defina um limite de tentativas e um tempo máximo total.
6) Crie fila (queue) para estabilizar o tráfego
Quando o evento de entrada chega em rajadas (ex.: dezenas de leads em segundos), coloque uma fila entre o gatilho e a API: grave itens em uma tabela/banco e processe num worker em ritmo constante. Isso transforma pico em fluxo contínuo, que é o que a maioria das APIs aguenta.
7) Garanta idempotência e deduplicação
Ao reprocessar após 429, o risco é duplicar: mandar duas mensagens, criar dois tickets, emitir duas notas, etc. Use chaves idempotentes (quando a API suporta), ou salve um “fingerprint” do evento (ex.: ID do pedido + ação) para não executar duas vezes.
8) Ajuste o desenho: batch, cache e menos chamadas
Troque N chamadas por 1: use endpoints de batch quando existirem, cache local de dados que não mudam toda hora (ex.: lista de produtos), e evite buscar o mesmo registro repetidamente dentro do loop.
9) Monitore para não descobrir pelo cliente
Crie alertas para taxa de erro 429, tempo de fila e tentativas de retry. O sinal de que você “resolveu” é: 429 raro e recuperável, sem atrasos imprevisíveis e sem duplicações.
O que o 429 quer dizer na prática (e por que ele aparece do nada)
429 é a API dizendo: “você passou do limite”. Esse limite pode ser por segundo, por minuto, por dia, por endpoint, por usuário, por token, por IP ou uma combinação disso.
O que confunde é que o fluxo pode funcionar 95% do tempo e falhar só em certos horários. A causa típica é concorrência: várias execuções simultâneas batendo no mesmo endpoint, ou um loop que dispara chamadas em alta velocidade.
Checklist rápido: qual solução combina com seu cenário?
Nem todo 429 se resolve do mesmo jeito. Use o mapa abaixo para escolher a intervenção com mais chance de estabilizar o fluxo sem “gambiarras”.
| Cenário comum | Sinal | Melhor correção |
|---|---|---|
| Loop grande (lista de pedidos/leads) | 429 depois de alguns itens | Throttle (atraso) + batch + limitar paralelismo |
| Webhooks em rajada (campanha, checkout) | 429 logo no início do pico | Fila (queue) + worker em ritmo fixo |
| Várias automações diferentes chamando a mesma API | 429 “aleatório” ao longo do dia | Rate limit centralizado (um único ponto de saída) + cache |
| Retries pioram o problema | Várias tentativas simultâneas geram mais 429 | Backoff exponencial + jitter + respeitar Retry-After |
| Duplicações após falha | Ações repetidas (mensagem/ticket/registro) | Idempotência + deduplicação por chave |
Retry com backoff e jitter: o padrão que realmente funciona
O erro mais comum que vemos em automações é retry fixo (ex.: “espera 1s e tenta de novo”). Isso cria sincronização: todo mundo tenta de novo junto e o 429 vira um ciclo.
Um padrão robusto: backoff exponencial (tempo dobra a cada tentativa) + jitter (variação aleatória) + limite de tentativas + limite de tempo total. Se a API enviar Retry-After, ele manda na sua espera.
- Exemplo de agenda de tentativas (ilustrativo): 1s, 2s, 4s, 8s, 16s (+/− jitter).
- Pare após X tentativas ou após Y minutos e mande o item para uma fila de reprocessamento manual/assíncrona (depende do seu processo).
- Registre o erro e o payload para reproduzir e ajustar o limite com dados reais.
Fila (queue) e controle de concorrência: a diferença entre “funciona” e “aguenta”
Se o seu volume é irregular (e quase sempre é), fila é o caminho mais estável. A fila desacopla entrada de processamento: o evento chega quando quiser; a API recebe em ritmo constante.
Controle de concorrência é o primo da fila: mesmo sem uma fila formal, limitar quantas execuções simultâneas podem chamar a API já corta a maioria dos 429.
- Fila simples: gravar itens (ID + ação + timestamp) e processar por ordem, com taxa máxima.
- Fila por prioridade: urgentes (ex.: confirmação de pagamento) passam na frente de rotinas (ex.: enriquecer CRM).
- Dead-letter: itens que falham após N tentativas vão para uma lista separada para análise.
Como evitar duplicação quando você reprocessa depois do 429
Toda vez que você adiciona retry, você adiciona o risco de repetir uma ação. Para ações que “não podem duplicar” (cobrança, mensagem, criação de pedido), idempotência não é luxo; é requisito.
Se a API permitir idempotency key, use. Se não permitir, implemente deduplicação do seu lado: salve um identificador único do evento (por exemplo, ID do pedido + tipo de ação) e não execute duas vezes.
Perguntas frequentes
Rate limit é o mesmo que bloqueio ou banimento?
Se eu aumentar o tempo de espera entre chamadas, resolve tudo?
Quantas tentativas de retry devo fazer?
O que muda quando a API envia o header Retry-After?
Leia também
Rate limit, retry e backoff: como parar de quebrar automação em API (n8n, Make, Zapier)
Guia direto para lidar com rate limit (429), retries e backoff em automações com APIs. Aprenda padrões práticos para n8n, Make e Zapier e evite falhas intermitentes, duplicidades e banimentos.
Ler →
Como monitorar automações (n8n, Make e Zapier): alertas, logs e erros sem virar refém do “falhou e ninguém viu”
Guia prático para monitorar automações em n8n, Make e Zapier: quais alertas criar, como registrar logs, tratar erros, retries e evitar falhas silenciosas.
Ler →
n8n não executa o workflow? Como achar o erro e depurar de verdade
Aprenda a depurar quando o n8n “não roda”: confirme o trigger, leia a última execução, isole o nó que trava e valide o dado real. Método prático para achar erro de verdade sem chute.
Ler →
O que é endpoint em automação e API? Exemplos e usos práticos
Entenda o significado de endpoint em automação e APIs, como funciona na prática e exemplos reais usados por empresas brasileiras. Explicação simples e objetiva para profissionais e iniciantes.
Ler →