Rate limits

300 requisições por minuto na v1. Headers de quota, status 429 e estratégias de backoff exponencial.

A API impõe rate limits pra proteger a infraestrutura compartilhada e garantir latência baixa pra todos. Os limites são generosos pra uso real: integrações típicas nem chegam perto. Mas se você está fazendo ETL ou sync inicial de muitos dados, vale entender os mecanismos.

Limite global

Plano	Requisições / minuto	Janela
Padrão	300	Sliding
Enterprise	Sob acordo	Sliding

A janela é sliding (não reseta no minuto cheio). Se você fez 300 chamadas entre 14:30:00 e 14:30:45, a próxima chamada só passa quando uma das antigas saiu da janela de 60s.

Limit por IP de origem

O contador é mantido por IP que chega ao servidor, não por API token. Se você tem múltiplos consumidores atrás do mesmo NAT/proxy, eles compartilham o orçamento. Pra isolamento real, use IPs distintos (workers em hosts diferentes).

Headers de quota

Toda resposta da API inclui:

Text

x-ratelimit-limit: 300
x-ratelimit-remaining: 287
x-ratelimit-reset: 1714680215

x-ratelimit-limit: limite total da janela.
x-ratelimit-remaining: quantas chamadas ainda restam.
x-ratelimit-reset: Unix timestamp de quando a janela libera a próxima vaga.

Use remaining proativamente pra throttlear seu cliente antes de bater no 429.

Status 429

Quando o limite estoura:

Text

HTTP/1.1 429 Too Many Requests
retry-after: 5
content-type: application/json

{
  "code": "rate_limit_exceeded",
  "message": "Limite de 300 req/min atingido."
}

O header Retry-After (em segundos) é a melhor heurística: ele já considera o sliding window e diz quando vai liberar a próxima vaga.

Estratégia de backoff

Text

async function withRetry(fn: () => Promise<Response>) {
  for (let attempt = 1; attempt <= 5; attempt++) {
    const res = await fn();
    if (res.status !== 429) return res;
    const retryAfter = Number(res.headers.get("retry-after") ?? 1);
    // Honra o servidor, mas com jitter pra evitar thundering herd.
    const jitter = Math.random() * 0.3 * retryAfter * 1000;
    await new Promise((r) => setTimeout(r, retryAfter * 1000 + jitter));
  }
  throw new Error("Rate limit persistente após 5 tentativas.");
}

Throttle no cliente

Em ETLs grandes, rate-limite seu próprio cliente abaixo do limite do servidor (ex.: 5 req/s = 300/min). Você nunca bate no 429, mantém latência estável e fica sendo um bom cidadão. Bibliotecas como bottleneck (Node) e asyncio.Semaphore (Python) ajudam.

Aumentar limites

Pra workspaces com volume real (>10M chamadas/mês), oferecemos plano Enterprise com limites customizados, IPs estáticos opcionais e SLA contratual. Fale com o time comercial direto pelo app web.

Bônus: prefira webhooks

Se você está pollando endpoints só pra detectar mudanças, troque por webhooks. O CRM dispara person.created, deal.won, etc. em tempo real. Zero rate limit, zero latência de polling. Veja Webhooks.