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.
curl -sS -i "$BUSINESS_API/customers?limit=1" \
-H "Authorization: Bearer $API_KEY"
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#
- Leia
RateLimit-Remainingem cada resposta e abrande quando se aproximar de zero. - Perante um
429, aguarde os segundos deRetry-Aftere só depois repita o mesmo pedido. - Em pedidos
POSTque criam recursos, envie sempre o mesmoIdempotency-Keyna repetição, para que um pedido recusado e repetido não crie dois registos.
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.