Limites de requisição

As duas camadas de rate limit da API e como lidar com respostas 429.

A API aplica limite de requisições em duas camadas independentes.

Camada por chave (API key)

O limite padrão é de 60 requisições por minuto por chave. Esse valor pode ser personalizado por chave (útil para integrações de maior volume). Quando o limite é excedido, a resposta é 429 RATE_LIMITED no formato canônico de erro, acompanhada dos headers Retry-After, X-RateLimit-Limit e X-RateLimit-Remaining — presentes apenas nessa resposta.

Camada por IP (infraestrutura)

Antes mesmo de chegar na sua chave, requisições a /api/* passam por um limite de 120 requisições por minuto por IP, aplicado na camada de infraestrutura. Se excedido, a resposta é 429 com corpo próprio ({ "error": "Too many requests" }, sem code) e header Retry-After fixo.

Ambas as camadas são aplicadas em memória, por instância do servidor — a aplicação do limite é best-effort, não uma garantia estrita como um WAF dedicado.

Retentativas

Ao receber um 429, aguarde o tempo indicado em Retry-After (segundos) antes de repetir a chamada. Para integrações de alto volume, recomendamos backoff exponencial com jitter.

Retry com backoff exponencial

async function callWithBackoff(fn, maxAttempts = 5) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    const res = await fn();
    if (res.status !== 429) return res;
    const retryAfter = Number(res.headers.get('Retry-After')) || 2 ** attempt;
    await new Promise((r) => setTimeout(r, retryAfter * 1000));
  }
  throw new Error('Limite de requisições excedido após várias tentativas');
}