Segurança

Rate limits

Entenda como a API limita requisições e como tratar bloqueios temporários.

Como funciona

A API aplica limites de requisições por janela de tempo para manter a estabilidade da plataforma e reduzir abuso. A proteção incide principalmente sobre endpoints públicos, mais expostos por não utilizarem Basic Auth.

O limite exato pode variar por endpoint e por perfil de operação. Ao atingir a capacidade permitida, novas chamadas são bloqueadas temporariamente até a renovação da janela.

Resposta HTTP 429

Quando o limite é excedido, a API responde com 429 Too Many Requests.

JSON

{  "detail": "Too Many Requests"}

{  "detail": "Too Many Requests"}

Headers de limite

Quando disponíveis, os headers abaixo ajudam sua aplicação a decidir quando repetir a chamada:

Retry-After

Quantidade de segundos a aguardar antes da próxima tentativa.

X-RateLimit-Limit

Total de requisições permitidas na janela atual.

X-RateLimit-Remaining

Quantidade de requisições ainda disponível.

Boas práticas

Respeite o header Retry-After antes de tentar novamente.
Implemente backoff exponencial com um limite de tentativas.
Evite polling agressivo; use webhooks para atualizações de status.
Não repita automaticamente operações não idempotentes sem confirmar o resultado anterior.

TypeScript

async function requestWithRetry(url, options, attempt = 0) {  const response = await fetch(url, options);
  if (response.status !== 429 || attempt >= 4) {    return response;  }
  const retryAfter = Number(response.headers.get("Retry-After"));  const delay = retryAfter    ? retryAfter * 1000    : Math.min(1000 * 2 ** attempt, 30000);
  await new Promise((resolve) => setTimeout(resolve, delay));  return requestWithRetry(url, options, attempt + 1);}

async function requestWithRetry(url, options, attempt = 0) {  const response = await fetch(url, options);
  if (response.status !== 429 || attempt >= 4) {    return response;  }
  const retryAfter = Number(response.headers.get("Retry-After"));  const delay = retryAfter    ? retryAfter * 1000    : Math.min(1000 * 2 ** attempt, 30000);
  await new Promise((resolve) => setTimeout(resolve, delay));  return requestWithRetry(url, options, attempt + 1);}