Limites de uso
Janelas de 1 minuto, contadas por chave, por organização e por IP. Toda resposta traz X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset (segundos até a janela reiniciar). Ao passar do limite, a resposta é 429 limite_excedido com Retry-After em segundos.
| O quê | Limite |
|---|---|
| Por chave | 300 requisições/min |
| Por organização (todas as chaves) | 600 requisições/min |
| Por IP de origem | 600 requisições/min |
Envio de mensagem (POST /mensagens), por chave | 60/min |
| Envio de mensagem, por organização | 120/min |
| Escritas em funil, agenda e equipe, por chave | 120/min |
| Escritas em funil, agenda e equipe, por organização | 240/min |
| Relatórios, por chave | 12/min (429 limite_relatorios) |
| Relatórios, por organização | 30/min |
| Corpo da requisição | até 64 KB (413 corpo_grande) |
| Itens por página | 1 a 100 (padrão 50) |
| Webhooks por organização | 10 |
Os números valem no plano atual e podem subir; o GET /me mostra os da sua organização em limites.
Como tratar o 429#
Espere os segundos de Retry-After e tente de novo. Para 5xx, tente de novo com espera crescente. Não repita 4xx (exceto 429): a mesma chamada vai falhar igual.
JavaScript
// Repete só o que vale repetir: 429 (limite) e 5xx (nosso lado).
// No POST /mensagens, repita sempre com a mesma Idempotency-Key.
async function chamar(url, opcoes, tentativas = 5) {
for (let i = 0; ; i++) {
const resposta = await fetch(url, opcoes);
const repetir = resposta.status === 429 || resposta.status >= 500;
if (!repetir || i >= tentativas) return resposta;
const espera = Number(resposta.headers.get('Retry-After')) || 2 ** i;
await new Promise((r) => setTimeout(r, espera * 1000));
}
}