Rate Limiting

Limites canônicos da API SignDocs Brasil, headers retornados, comportamento esperado e como pedir aumento de quota.

Limites em camadas

A API aplica rate limiting em duas camadas:

1. WAF (camada de borda, anti-abuso)

• 2 000 requisições por IP a cada 5 minutos em endpoints públicos como /oauth2/token.
• Resposta ao exceder: HTTP 403 Forbidden vinda do CloudFront, sem JSON Problem Details (a requisição nunca chega ao backend).
• Apropriado para pendurar lógica de circuit breaker no cliente — IPs disparados continuam bloqueados até o fim da janela de 5 min.

2. API Gateway por tenant

Quotas por tenant variam por plano, controladas pelo client_id do token Bearer. Quando você está rate-limited pelo Gateway, recebe HTTP 429 Too Many Requests com Problem Details no corpo:

{
  "type": "https://signdocs.com.br/problems/rate-limit-exceeded",
  "title": "Rate limit excedido",
  "status": 429,
  "detail": "Cliente excedeu a quota do plano. Tente novamente em 12 segundos.",
  "instance": "/v1/transactions"
}

Headers de resposta

Todas as respostas da API (sucesso ou erro) carregam:

Header	Significado	Exemplo
RateLimit-Limit	Máximo de requisições permitidas na janela atual	100
RateLimit-Remaining	Requisições ainda disponíveis na janela	97
RateLimit-Reset	Unix timestamp (segundos) para o reset da janela	1714325400
Retry-After	Segundos a aguardar (presente em 429)	12

Padrão segue draft IETF draft-ietf-httpapi-ratelimit-headers.

Comportamento esperado do cliente

1. Sempre respeitar Retry-After quando recebe 429.
2. Implementar backoff exponencial com jitter — começar em ~1s, dobrar a cada falha consecutiva, com teto em 60s.
3. Não loopar requisições de retry sem limite — após 5 tentativas, propagar o erro para o consumidor.
4. Monitorar RateLimit-Remaining em métricas operacionais — se cair para perto de zero rotineiramente, a quota está dimensionada errada para o caso de uso.

Exemplo de pseudocódigo:

async function callWithBackoff(req: () => Promise<Response>) {
  const maxAttempts = 5;
  let attempt = 0;
  while (attempt < maxAttempts) {
    const res = await req();
    if (res.status !== 429) return res;
    const retryAfter = Number(res.headers.get('Retry-After') ?? 1);
    const jitter = Math.random() * 0.5;
    await sleep((retryAfter + jitter) * 1000);
    attempt += 1;
  }
  throw new Error('Rate limit persistente após retries');
}

Quotas por plano

Os números abaixo são padrão; clientes Enterprise podem negociar limites diferentes.

Plano	Transações/mês	Sandbox/dia	Biometria/dia (HML)
Iniciante	10 000	500	250
Avançado	50 000	500	250
Enterprise	250 000+	conforme contrato	conforme contrato

Picos planejados (campanhas, lançamentos)

Para necessidades pontuais que excederão a quota habitual (campanhas de marketing, picos sazonais, importações em massa), abra ticket com pelo menos 5 dias úteis de antecedência em suporte@signdocs.com.br informando:

• Janela esperada do pico (data, hora UTC, duração)
• Pico de RPS estimado e total de transações no período
• Endpoints mais carregados
• Plano de fallback se a SignDocs Brasil não puder acomodar

A SignDocs Brasil ajusta limites temporariamente sem custo dentro do dimensionamento do plano. Sustentado, requer upgrade.

Consequências de abuso

Picos não anunciados e padrões suspeitos disparam o pipeline anti-abuso descrito em aup.md:

1. Throttling automático (continuação de 429 com Retry-After mais longo)
2. Suspensão temporária da chave (24-72h)
3. Suspensão contratual

Disputa de classificação anti-abuso: suporte@signdocs.com.br. Caso envolva suspeita de comprometimento da chave: security@signdocs.com.br.

Endpoints isentos do rate limit por tenant

Apenas:

• GET /health (probes externos)
• GET /v1/verify/{evidenceId} (verificador público — tem rate limit por IP do verificador, não por tenant)
• GET /v1/verify/envelope/{envelopeId} (idem)

Esses endpoints continuam sujeitos ao WAF.