Limite de requisições

Quanto cabe, como saber quanto sobrou e o que fazer no 429.

O limite é por organização, e não por chave. Criar dez chaves não multiplica o teto — como o cliente divide o dele entre integrações é escolha dele.

O teto

600 requisições por minuto, em janela deslizante. Vale para todas as rotas somadas, nos dois ambientes.

Saber quanto sobrou

Os três cabeçalhos vão em toda resposta, inclusive nas bem-sucedidas. É o que permite desacelerar antes de levar 429.

X-RateLimit-Limit       600
X-RateLimit-Remaining   587
X-RateLimit-Reset       1756240060

X-RateLimit-Reset é o instante em que a janela vira, em segundos desde a época.

Quando excede

HTTP/1.1 429 Too Many Requests
Retry-After: 15
X-RateLimit-Remaining: 0

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Slow down and retry after the window resets.",
    "retry_after": 15,
    "request_id": "req_01K7ZFA5X8Q2M4N6P8R0T2V4W6"
  }
}

Respeite o `Retry-After`

Repetir imediatamente depois de um 429 mantém você no teto e não entrega nada. Espere o que o cabeçalho diz — ele é o tempo exato até a janela virar, não uma estimativa.

JavaScript

async function chamarComRecuo(url, opcoes, tentativas = 3) {
  for (let tentativa = 0; tentativa < tentativas; tentativa += 1) {
    const resposta = await fetch(url, opcoes);
    if (resposta.status !== 429) return resposta;

    // O cabeçalho diz o tempo exato. Chutar é o que mantém você no teto.
    const espera = Number(resposta.headers.get("retry-after") ?? 1);
    await new Promise((resolve) => setTimeout(resolve, espera * 1000));
  }
  throw new Error("Limite de requisições excedido depois de várias tentativas.");
}

Precisa de mais? Fale com a gente. O limite é configurável por conta, e a arquitetura já prevê tetos diferentes por plano.

Veja também Erros.

Escrevemos sobre operação de atendimento, canais e IA no blog da Amivu.