Rate Limit da API Não Oficial do WhatsApp
Para proteger a estabilidade da conexão e evitar bloqueios pelo WhatsApp, a plataforma aplica um controle automático de velocidade de envio nas conexões de API Não Oficial. Esse mecanismo é chamado de rate limit e define quantas mensagens podem ser disparadas por canal em um determinado intervalo de tempo.
Quando o limite é atingido, a plataforma não descarta a mensagem: ela é retida e reenviada automaticamente assim que o canal estiver liberado.
Qual é o limite de envio?
O limite varia conforme o tipo de mensagem enviada, já que mídias (imagem, vídeo, áudio e documento) exigem mais recursos de processamento do que mensagens de texto.
Somente texto
~10 mensagens a cada 10 seg
Somente mídia (imagem etc.)
~3 mensagens a cada 10 seg
Mix (texto + mídia)
Depende da proporção
Exemplo prático: enviar 7 textos e 1 imagem já equivale ao limite máximo de um intervalo. A partir daí, o próximo envio aguarda o ciclo reiniciar.
O limite é por canal: cada número de WhatsApp conectado à plataforma tem sua própria contagem independente. Operações com múltiplos canais não interferem umas nas outras.
O que acontece quando o limite é atingido?
Ao atingir o limite, o canal recebe um bloqueio temporário. A plataforma detecta isso automaticamente e inicia um ciclo de retentativas progressivas, aumentando o intervalo de espera a cada nova tentativa para não sobrecarregar o canal.
1ª e 2ª
5 segundos
3ª a 5ª
17 a 25 segundos
6ª a 10ª
~1 a 2 minutos
11ª a 20ª
~4 a 7 minutos
21ª em diante
~10 minutos ou mais
Esse processo ocorre de forma totalmente automática e invisível para o atendente. A mensagem permanece na fila interna até ser entregue com sucesso.
O que é o erro H522?
Se após 1 hora de retentativas a mensagem ainda não conseguiu ser enviada, a plataforma considera que o canal não tem capacidade de entregar aquela mensagem e encerra o processo.
Nesse caso:
A mensagem é marcada com status de Falha
O erro H522 é registrado com a descrição: "A quantidade de disparos excedeu a capacidade do canal"
O atendente ou administrador pode visualizar esse detalhe no histórico da conversa
O erro H522 não é recuperável automaticamente. Caso ele ocorra com frequência, é recomendável revisar o volume de disparos ou distribuir o envio entre mais canais.
Como evitar atingir o limite?
Espaçe os disparos em campanhas: ao configurar envios em massa, utilize intervalos entre as mensagens para não saturar o canal.
Prefira texto quando possível: mensagens de texto consomem menos capacidade do que mídias.
Use múltiplos canais: distribua os envios entre diferentes números de WhatsApp para aumentar a capacidade total.
Monitore o status do canal: acompanhe o Status de Integridade do Canal para identificar instabilidades antes que afetem os envios.
Detalhes Técnicos
Esta seção descreve como o mecanismo de rate limit funciona internamente.
Configuração do Rate Limit
Limite de pontos
10 pontos por janela
Tamanho de cada janela
10 segundos
Janelas analisadas
3 (30 segundos no total)
Retry após bloqueio
5 segundos
Peso por tipo de mensagem
Texto
1 ponto
Imagem
3 pontos
Áudio
3 pontos
Vídeo
3 pontos
Documento
3 pontos
Como o limite é calculado
O sistema utiliza uma janela deslizante com média:
A cada envio, o sistema analisa os últimos 30 segundos divididos em 3 janelas de 10 segundos
Calcula a média de pontos consumidos nessas 3 janelas
Se a média for ≥ 10 pontos, a mensagem é bloqueada
Se a média for inferior, o envio é registrado e o contador incrementa com o peso do tipo daquela mensagem
Há também uma detecção rápida: se a janela atual já acumulou 10 pontos ou mais, o bloqueio ocorre imediatamente, sem calcular a média.
Backoff progressivo das retentativas
O intervalo de espera entre cada tentativa cresce progressivamente conforme a fórmula abaixo:
1ª e 2ª
—
5 segundos (padrão)
3ª a 5ª
4×
5 + (4 × nº da tentativa) segundos
6ª a 10ª
10×
5 + (10 × nº da tentativa) segundos
11ª a 20ª
20×
5 + (20 × nº da tentativa) segundos
21ª em diante
30×
5 + (30 × nº da tentativa) segundos
Após 1 hora sem sucesso, o sistema encerra as tentativas e registra o erro H522 com status FAILED na mensagem.
Atualizado