Como mitigar o erro HTTP 429 (Too Many Requests).

Rate Limit INTERNO

O controle de Rate Limit funciona através de uma janela de tempo com contagem de requisições por cliente. Cada cliente é identificado por informações como IP, token, API Key ou usuário autenticado.

Por exemplo, considerando um limite de 120 requisições por minuto: na primeira chamada é criado um contador temporário com duração de 60 segundos. Cada nova requisição do mesmo identificador incrementa esse contador.

Ao atingir o limite configurado, novas requisições recebem o retorno HTTP 429 Too Many Requests até que a janela expire. Após esse período, o contador é reiniciado automaticamente e uma nova janela começa.

A contagem não é sincronizada com o relógio (“virada do minuto”). O tempo é contado a partir da primeira requisição do ciclo. Exemplo: se a primeira chamada ocorrer às 10:00:15, a janela será válida até 10:01:15.

Internamente, os contadores são armazenados temporariamente em cache para garantir validação rápida e alta performance mesmo sob grande volume de requisições.

O modelo utilizado é semelhante a um Fixed Window com expiração dinâmica, ou seja, utiliza um contador fixo durante a janela configurada, sem reprocessar continuamente os últimos segundos como ocorre em modelos Sliding Window.

Os erros HTTP 429 normalmente acontecem quando a integração excede o volume permitido dentro da janela. As causas mais comuns incluem:

• loops involuntários;
• retries automáticos;
• múltiplas requisições simultâneas;
• polling excessivo;
• jobs concorrentes;
• múltiplos sistemas utilizando a mesma credencial.

Dependendo da estratégia de identificação utilizada, clientes compartilhando o mesmo IP público também podem consumir o mesmo limite conjuntamente.

A API também pode retornar headers informando o limite atual, quantidade restante e tempo
para liberação, como:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 18
Retry-After: 42

O Retry-After informa quantos segundos faltam para o cliente voltar a realizar novas
requisições sem bloqueio.

Para evitar esse tipo de problema, o recomendado é implementar controle de concorrência,
evitar loops, reduzir polling excessivo e utilizar retry com backoff exponencial ao invés de tentar
reenviar imediatamente após um 429.

Rate Limit CLOUDFLARE

O Rate Limit da Cloudflare é mais simples, ele funciona por IP em um determinado intervalo, a
partir da primeira request por 10 segundos, por exemplo, você chamou uma rota com o IP
127.0.0.1, a partir desta chamada você tem um limite de chamadas do mesmo IP por 10
segundos, após os 10 segundos isto se renova.

O nosso limite é de 20 chamadas a cada 10 segundos (2 por segundo) somente para as rotas
de API que passam pelo domínio principal (app.plugsign.com.br), caso alcance o valor, o IP
será bloqueado por 10 segundos, e após isto liberado.

Funcionamento do Controle de Taxa de Requisições

Visão Geral
Nossa API possui um mecanismo de controle de taxa de requisições (Rate Limit) utilizado para
garantir estabilidade, segurança e disponibilidade da plataforma.

O modelo utilizado trabalha com:

● contagem de requisições por cliente;
● armazenamento temporário em cache;
● janela temporal com expiração automática;
● bloqueio temporário ao exceder o limite configurado.

Quando o limite é ultrapassado, a API responde com:

429 Too Many Requests

O bloqueio é temporário e liberado automaticamente após o término da janela de tempo.

Como o Rate Limit funciona internamente

Cada cliente possui um contador temporário associado a um identificador.

Esse identificador pode ser:
● token;

Exemplo lógico:
cliente_X:
requests: 87
expiração: 32 segundos

A cada nova requisição:
1. o sistema identifica o cliente;
2. consulta o contador atual;
3. incrementa o contador;
4. verifica o limite configurado;
5. permite ou bloqueia a request.

Modelo de Janela Utilizado
O mecanismo utilizado funciona baseado em uma estratégia próxima de:

Fixed Window com expiração dinâmica
Ou seja:
● a janela começa na primeira requisição;
● o contador permanece válido até o tempo de expiração;
● após a expiração o contador é removido automaticamente;
● uma nova janela é iniciada.

Exemplo Prático

Configuração:
120 requisições por 60 segundos

Fluxo real
Primeira request:
10:00:15

Nesse momento:
● o contador é criado;
● inicia a janela de 60 segundos;
● expiração definida para:
10:01:15

Durante a janela
As requests continuam incrementando o mesmo contador:
10:00:20 → request 2
10:00:31 → request 15
10:00:45 → request 89
10:01:02 → request 120

Excedendo o limite
A próxima request:
10:01:03 → request 121
receberá:
429 Too Many Requests

Liberação automática

Quando chegar:
10:01:15
o contador expira automaticamente.
A próxima request cria uma nova janela.

Características importantes desse modelo
A janela não segue o relógio absoluto
O reset não acontece exatamente:

00:00
00:01
00:02

Ela depende da primeira requisição do ciclo.

Exemplo
Se a primeira request ocorrer:
14:37:12
a janela será válida até:
14:38:12

Como o armazenamento funciona
O Rate Limit utiliza armazenamento temporário em cache.
Cada cliente possui uma chave semelhante a:
rate_limit:cliente_X

Essa chave armazena:
● quantidade de requests;
● timestamp de expiração.

Estrutura lógica simplificada

rate_limit:cliente_X
contador: 120
TTL: 18 segundos

Como o bloqueio acontece
Quando o contador ultrapassa o limite configurado:
1. novas requests são negadas temporariamente;
2. o sistema mantém o bloqueio até o TTL expirar;
3. após a expiração o acesso volta automaticamente.
Não existe bloqueio permanente.

Comportamento da Janela
O modelo utilizado não trabalha com Sliding Window real.
Ou seja:
❌ não recalcula continuamente os últimos 60 segundos.
O sistema trabalha com:
✅ contador fixo com expiração automática.

Recomendações para integrações
Implementar backoff exponencial
Ao receber 429:
✅ recomendado:
1s
2s
4s
8s
16s
❌ evitar retry imediato contínuo.

Respeitar Retry-After
Se retornado:
Retry-After: 30
aguardar o período informado antes de tentar novamente.

Reduzir polling
Preferir:
● webhooks;
● filas;

● cache local;
● sincronização incremental.

Como investigar bloqueios
Ao receber HTTP 429, recomendamos verificar:

1. Quantidade de requests
Analisar:
● requests/minuto;
● simultaneidade;
● endpoints mais acessados.

2. Loops e retries
Verificar:
● retries automáticos;
● reconexões;
● jobs concorrentes;
● polling.

3. Frequência das chamadas
Evitar chamadas excessivamente frequentes.

4. Compartilhamento de credenciais
Múltiplos sistemas utilizando a mesma API Key podem consumir o mesmo limite.

Headers normalmente retornados
A API pode retornar headers informativos:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 18
Retry-After: 42

Significado dos headers

Header Descrição

X-RateLimit-Limit Limite máximo permitido

X-RateLimit-Remaining Quantidade restante disponível

Retry-After Tempo restante até nova liberação