Limite de requisições

Rate limit de 60 requisições por minuto por workspace, headers de controle e como tratar o 429.

A API externa aplica um limite de 60 requisições por minuto por workspace. O contador é compartilhado por todos os endpoints e por todas as instâncias da sua integração — o que importa é o total de chamadas feitas com a sua API key.

Headers de controle

Toda resposta autenticada traz três headers:

Header	Significado
`X-RateLimit-Limit`	Teto de requisições na janela (padrão: `60`)
`X-RateLimit-Remaining`	Quantas requisições ainda cabem na janela atual
`X-RateLimit-Reset`	Timestamp Unix (em segundos) em que a janela reinicia

Exemplo de headers

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1786301340

Monitore o Remaining

Ler X-RateLimit-Remaining em cada resposta é mais barato do que reagir ao 429. Quando o valor cair abaixo de ~10, reduza a cadência antes de estourar o limite.

Quando o limite estoura

Chamadas acima do teto recebem 429:

429 Too Many Requests

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again later."
  }
}

O 429 é temporário e seguro para retry. Espere até o instante indicado em X-RateLimit-Reset e tente de novo, preferencialmente com backoff exponencial e jitter.

Retry com backoff

async function chamarComRetry(url, options, tentativa = 0) {
  const response = await fetch(url, options);

  if (response.status !== 429 || tentativa >= 5) {
    return response;
  }

  const reset = Number(response.headers.get('X-RateLimit-Reset')) * 1000;
  const esperaPadrao = 2 ** tentativa * 1000 + Math.random() * 500;
  const espera = Number.isFinite(reset) ? Math.max(reset - Date.now(), esperaPadrao) : esperaPadrao;

  await new Promise((resolve) => setTimeout(resolve, espera));

  return chamarComRetry(url, options, tentativa + 1);
}

Dois 429 diferentes

RATE_LIMIT_EXCEEDED significa excesso de requisições válidas — espere e repita. TOO_MANY_AUTH_FAILURES significa excesso de tentativas com chave inválida — não repita, corrija a chave (ver Autenticação).

Prefira lotes a chamadas individuais

O limite é por requisição, não por registro. Um lote de 1000 notificações consome uma requisição; mil chamadas individuais consomem mil.

Cenário	Chamadas	Recomendação
1 notificação avulsa	1	Criar notificação
Até 1000 registros	1	Lote via JSON
Acima de 1000 registros	1 por arquivo	Upload de planilha

Para volumes acima de 1000 itens via JSON, faça chamadas sucessivas reutilizando o mesmo batchCode — os itens são agregados no mesmo lote.

Indisponibilidade do controle

Se o mecanismo de rate limit ficar indisponível, a API responde 503 e recusa a requisição em vez de deixá-la passar sem controle:

503 Service Unavailable

{
  "success": false,
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Rate limiting backend is temporarily unavailable. Please retry shortly."
  }
}

Trate como erro transitório: repita com backoff.

Limite personalizado

Integrações com volume comprovadamente maior podem receber um teto customizado, configurado por chave. Nesse caso o valor aparece em X-RateLimit-Limit. Fale com o seu contato comercial apresentando o volume estimado de requisições por minuto.