PT EN

Limites de pedidos

Cada chave de API tem um orçamento de 100 pedidos por segundo. Leia os cabeçalhos RateLimit-*, trate a resposta 429 e repita só depois de Retry-After.

Como o limite funciona#

O limite aplica-se a cada chave de API, não à conta: duas chaves da mesma empresa têm orçamentos independentes. Cada chave pode fazer 100 pedidos por segundo, contados em janelas de um segundo. Quando o servidor guarda as contagens na base de dados, todas as réplicas partilham a mesma janela; se essa contagem partilhada falhar, cada processo aplica o mesmo orçamento localmente.

O limite vale em todas as áreas da API (Business, Consumer, Platform, Public e Connector) sempre que o pedido apresenta uma chave. Pedidos feitos com a sessão do painel ou com um token OAuth não passam por este limitador e não recebem os cabeçalhos abaixo. Ao rodar uma chave, a nova recebe um ID novo e, com ele, um orçamento próprio.

Cabeçalhos em cada resposta#

Todas as respostas a um pedido feito com chave trazem três cabeçalhos:

Cabeçalho Significado
RateLimit-Limit Pedidos permitidos por janela (100).
RateLimit-Remaining Pedidos que ainda restam na janela actual.
RateLimit-Reset Segundos, arredondados para cima, até a janela recomeçar.

Quando o orçamento se esgota, a resposta é 429 Too Many Requests e inclui também Retry-After, com o mesmo valor de RateLimit-Reset.

bash
curl -sS -i "$BUSINESS_API/customers?limit=1" \
  -H "Authorization: Bearer $API_KEY"
http
HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
RateLimit-Limit: 100
RateLimit-Remaining: 0
RateLimit-Reset: 1
Retry-After: 1
Request-Id: req_7f3a9c21d04b4e6f8a12b5c9e0d7f364

{
  "type": "about:blank",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "This API key (sk_rtest_C3J2) exceeded its request budget; retry after the RateLimit-Reset seconds.",
  "instance": "$BUSINESS_API/customers",
  "code": "RATE_LIMITED",
  "error_code": "request.rate_limited",
  "request_id": "req_7f3a9c21d04b4e6f8a12b5c9e0d7f364"
}

O detail identifica a chave pelo prefixo, nunca pelo segredo. Se o operador tiver configurado o site de documentação, type aponta para a âncora request.rate_limited da página de erros; caso contrário vale about:blank. Trate o erro pelo error_code e não pelo texto.

Repetir com segurança#

  1. Leia RateLimit-Remaining em cada resposta e abrande quando se aproximar de zero.
  2. Perante um 429, aguarde os segundos de Retry-After e só depois repita o mesmo pedido.
  3. Em pedidos POST que criam recursos, envie sempre o mesmo Idempotency-Key na repetição, para que um pedido recusado e repetido não crie dois registos.
javascript
async function comLimite(url, options, tentativas = 3) {
  for (let i = 0; i < tentativas; i++) {
    const res = await fetch(url, options);
    if (res.status === 429) {
      const espera = Number(res.headers.get("Retry-After") || "1");
      await new Promise((r) => setTimeout(r, espera * 1000));
      continue;
    }
    return res;
  }
  throw new Error("orçamento da chave esgotado");
}

A CLI gotactl já faz isto: perante um 429 espera Retry-After (um segundo, se o cabeçalho faltar) e tenta mais duas vezes; se a terceira tentativa também for recusada, termina com o código de saída 5.

Outros limites#

Alguns pontos sem chave, como os pedidos públicos e o início de sessão, têm orçamentos próprios e respondem igualmente 429 com Retry-After, mas sem os cabeçalhos RateLimit-*. Os pedidos de uma chave recusados pelo limitador continuam a aparecer em Programadores > Registos, com o estado 429.

Próximos passos#