Limites de requisição

Visão geral

A API aplica cinco camadas de rate limiting. As três primeiras valem para qualquer requisição; as duas últimas só para envio de mensagem:

Camada	Descrição
Minuto	Limite principal de requisições por minuto
Burst	Limite de curto prazo (10 segundos) para picos
Diário	Limite total de requisições por dia
Por número do WhatsApp	30 mensagens/minuto, independente do plano
Por página do Messenger	30 mensagens/minuto, independente do plano

Limites por plano

Plano	Por minuto	Burst (10s)	Por dia
Starter	60	20	10.000
Growth	120	40	50.000
Scale	300	100	200.000
Enterprise	600	200	500.000

Limites por canal (envio de mensagens)

Independente do plano, o envio de mensagens tem limites adicionais por canal:

Canal	Limite	Código do erro
WhatsApp — por número	30 mensagens/minuto	`WHATSAPP_INSTANCE_RATE_LIMIT`
Messenger — por página	30 mensagens/minuto	`MESSENGER_PAGE_RATE_LIMIT`

Estes limites são por canal e independentes do plano: eles continuam valendo mesmo com folga no limite por minuto da sua chave. Um disparo grande para o mesmo número esbarra aqui antes de esbarrar no limite do plano.

Headers de rate limit

Cada resposta bem-sucedida inclui headers informativos:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 2026-06-10T15:31:00.000Z

Header	Descrição
`X-RateLimit-Limit`	Limite total por minuto do seu plano
`X-RateLimit-Remaining`	Requisições restantes no minuto atual
`X-RateLimit-Reset`	Timestamp ISO 8601 de quando o limite reseta

Quando o limite é atingido

Ao exceder qualquer limite, a API retorna HTTP 429:

{
  "error": {
    "type": "rate_limit_exceeded",
    "message": "Limite de 60 requests/min atingido. Tente novamente em 15s.",
    "code": "RATE_LIMIT_EXCEEDED",
    "retry_after": 15
  },
  "meta": {
    "request_id": "req_a1b2c3d4e5f6a7b8"
  }
}

O header Retry-After indica quantos segundos aguardar antes de tentar novamente.

Como implementar retry

async function fetchWithRetry(url, options = {}, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    if (response.status !== 429) return response;
    
    const retryAfter = parseInt(response.headers.get('Retry-After') || '5');
    const backoff = retryAfter * 1000 * Math.pow(2, attempt);
    
    console.log(`Rate limited. Aguardando ${backoff / 1000}s...`);
    await new Promise(r => setTimeout(r, backoff));
  }
  
  throw new Error('Máximo de tentativas atingido');
}

import requests
import time

def fetch_with_retry(url, headers, max_retries=3, **kwargs):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers, **kwargs)
        
        if response.status_code != 429:
            return response
        
        retry_after = int(response.headers.get('Retry-After', 5))
        backoff = retry_after * (2 ** attempt)
        
        print(f'Rate limited. Aguardando {backoff}s...')
        time.sleep(backoff)
    
    raise Exception('Máximo de tentativas atingido')

Boas práticas

Distribua requisições no tempo — evite enviar 60 requisições simultâneas no início de cada minuto
Implemente retry com backoff — sempre respeite o Retry-After e adicione backoff exponencial
Use limit=100 — maximizar o limit reduz o número de requisições para buscar muitos registros
Filtre no lado servidor — use os parâmetros de filtro disponíveis em vez de filtrar no cliente
Cache dados estáticos — membros, funis de venda e instâncias mudam pouco; cache por alguns minutos

Introdução

Fundamentos

Guias

Plataforma

Visão geral

Limites por plano

Limites por canal (envio de mensagens)

Headers de rate limit

Quando o limite é atingido

Como implementar retry

Boas práticas

​Visão geral

​Limites por plano

​Limites por canal (envio de mensagens)

​Headers de rate limit

​Quando o limite é atingido

​Como implementar retry

​Boas práticas

Visão geral

Limites por plano

Limites por canal (envio de mensagens)

Headers de rate limit

Quando o limite é atingido

Como implementar retry

Boas práticas