Rate Limits

Rate limits protegem a plataforma e garantem qualidade de serviço para todos os tenants. Aplicamos três camadas independentes, e a primeira que estourar responde 429:

1. Por chave de API: janela por minuto, com o limite definido na própria key
2. Por IP e por tenant: defesa contra abuso, contada em janela de 1 hora
3. Por endpoint: controle granular em endpoints caros (emissão de relatório, coleta de fingerprint, operações administrativas)

Limite da sua chave

O limite da superfície de API key é por chave e por minuto, e é definido no momento em que a key é criada, no console, em Desenvolvedores, API Keys, campo rate_limit_per_min. O valor aceito vai de 1 a 60.000 requisições por minuto. Key criada sem esse campo cai no default do servidor, que é 60 requisições por minuto.

Cuidado

Não existe hoje uma tabela de limites por plano comercial implementada no servidor: nenhum código lê o plano do tenant para calcular rate limit. O que vale é o número gravado na sua chave e os tetos de infraestrutura abaixo. Se você recebeu um número por contrato, confirme com o suporte que ele foi aplicado na key, porque a plataforma não o deriva do plano sozinha.

Tetos de infraestrutura aplicados acima da sua chave, em janela de 1 hora:

Camada	Limite	Observação
Por IP	5.000 req/h	Vale para toda a API
Por tenant	100.000 req/h	Vale para toda a API
Login e autenticação	1.000 req/h por IP	Janela separada, protege /auth/*

Endpoints caros têm um teto próprio por hora, aplicado antes do handler. Exemplos medidos: emissão de relatório regulatório, 50 por hora; coleta de fingerprint e operações administrativas, 600 por hora. Esses endpoints respondem 429 com Retry-After: 3600.

Headers de quota

Os headers de quota não aparecem em toda resposta. Eles são emitidos apenas pelas rotas que passam por um limitador que os escreve:

Header	Onde aparece	Significado
X-RateLimit-Limit	Superfície de API key, busca de clientes, rate limit por ator e endpoints com teto horário	Limite da janela daquele limitador
X-RateLimit-Remaining	Mesmas rotas acima	Quantas chamadas restam na janela corrente
X-RateLimit-Reset	Busca de clientes e rate limit por ator	Duração da janela em segundos (por exemplo 60), e não um unix timestamp

Na superfície de API key (/api/v1/vasp/*), a resposta traz:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 587

Cuidado

Não existe o header X-RateLimit-Scope. Ele nunca foi emitido pelo servidor. Consumidor que dependa dele lê string vazia.

Os limitadores por IP e por tenant que valem para toda a API não emitem headers de quota: eles só se manifestam no 429 com Retry-After.

Resposta 429

O envelope do 429 depende de qual camada disparou. Trate sempre pelo status HTTP e pelo header Retry-After, que estão presentes nos dois casos.

Superfície de API key:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

{
  "success": false,
  "error": {
    "code": "api_key_rate_limit_exceeded",
    "message": "API key rate limit exceeded"
  }
}

Limitador por IP, por tenant ou por endpoint:

HTTP/1.1 429 Too Many Requests
Retry-After: 3600
Content-Type: application/json

{
  "success": false,
  "error": "Too many requests. Please try again later.",
  "retry_after": 3600
}

Cuidado

Repare que error é um objeto no primeiro caso e uma string no segundo. Não escreva err.error.code sem checar o tipo. Não existe o código RATE_LIMITED em nenhuma resposta do servidor.

Boas práticas

1. Respeite Retry-After

Não chute o backoff: use o header. Ele vem em segundos e reflete a janela real do limitador que disparou.

2. Use Idempotency-Key onde a rota suporta

curl -X POST https://api.crypto.sentinexrisk.com/api/v1/vasp/screenings \
  -H "Idempotency-Key: txn_12345_attempt_1" \
  -H "X-API-Key: $SENTINEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d @payload.json

O suporte a Idempotency-Key é por rota, não global. Ver Idempotência para a lista do que foi medido.

3. Webhook em vez de polling

Não fique batendo GET /vasp/alerts?status=OPEN. Assine alert.created e receba push (ver Webhooks).

4. Cache no seu lado, sem depender de header nosso

A API não emite ETag e não emite Cache-Control: max-age em rota de leitura: onde há header de cache, ele é no-store ou no-cache. Se você quiser cachear leitura pouco volátil, faça isso no seu serviço com um TTL escolhido por você, ciente de que o dado pode ter mudado.

Aumentar limite

1. Ajuste o rate_limit_per_min da key no console, em Desenvolvedores, API Keys
2. Para elevar os tetos de IP, tenant ou endpoint, ou para picos programados: dev-support@sentinexrisk.com com (a) RPS desejado, (b) janela de pico, (c) justificativa

Ambiente de testes

O sandbox público ainda está em provisionamento e não tem hostname dedicado publicado. Para teste funcional, use a chave de ambiente de teste (snxc_test_...) fornecida pelo suporte, com o limite por minuto acordado gravado na própria chave.