Limites de uso

Requisições por minuto

Cada chave de API pode fazer 120 requisições por minuto. A contagem é por chave: duas integrações com chaves diferentes têm limites independentes.

As respostas trazem o estado do limite nos cabeçalhos:

Cabeçalho	Exemplo	Significado
X-RateLimit-Limit	120	Requisições permitidas por minuto para esta chave.
X-RateLimit-Remaining	87	Quantas ainda restam na janela atual.
X-RateLimit-Reset	1794407460	Quando a janela reinicia, em Unix timestamp (segundos).

O mesmo estado aparece em GET /me, no objeto rate_limit.

Quando o limite estoura

A API responde 429 com o código rate_limit_exceeded e o cabeçalho Retry-After com quantos segundos esperar:

HTTP/1.1 429 Too Many Requests
Retry-After: 18
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1794407460

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Limite de requisições por minuto excedido.",
    "request_id": "req_9a8b7c6d5e4f"
  }
}

Espere o tempo do Retry-After e tente de novo:

Retentativa respeitando o Retry-After (Node.js)

async function comRetentativa(fazerRequisicao, tentativas = 3) {
  for (let i = 0; i < tentativas; i++) {
    const res = await fazerRequisicao();
    if (res.status !== 429) return res;
    const espera = Number(res.headers.get('Retry-After') ?? 1);
    await new Promise((r) => setTimeout(r, espera * 1000));
  }
  throw new Error('Limite de requisições excedido várias vezes seguidas.');
}

Como gastar menos requisições

• Use webhooks em vez de consultar a API em loop. Em vez de perguntar a cada segundo “chegou mensagem?”, deixe a TopTalking avisar o seu sistema.
• Peça páginas maiores com limit=100 quando for ler muitos itens.
• Guarde em cache o que muda pouco, como etapas do Kanban e canais.
• Espalhe envios em lote ao longo do tempo — é melhor para o limite e, principalmente, para a saúde do seu número de WhatsApp. Veja Boas práticas no WhatsApp.

Outros limites

Item	Limite
Chaves de API ativas	25 por organização
Webhooks	10 por organização
Itens por página (limit)	1 a 100 (padrão 20)
Texto de uma mensagem	4096 caracteres
Anexos de uma mensagem agendada	10
Antecedência de uma mensagem agendada	até 365 dias
Validade de uma Idempotency-Key	24 horas
Histórico de eventos de webhook	30 dias