Rate Limits

Rate limits protegem a plataforma e garantem qualidade de serviço para todos os tenants. Aplicamos três camadas:

1. Por IP: defesa contra abuso (botnets, scraping)
2. Por tenant: proteção contra explosão de tráfego de um cliente
3. Por endpoint: controle granular em endpoints caros (KYT, OSINT)

Limites por plano

Plano	Tenant global (rpm)	KYT scoring (rps)	Listings/dashboard (rpm)
Starter	600	5	100
Growth	3.000	25	500
Pro	12.000	100	2.000
Enterprise	Negociável	Negociável	Negociável

Dica

Sandbox (sandbox.api.crypto.sentinexrisk.com) tem rate-limit fixo de 10 rpm por tenant: suficiente para testes funcionais, não para load test.

Headers de quota

Toda resposta inclui:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 587
X-RateLimit-Reset: 1747584000
X-RateLimit-Scope: tenant

Header	Significado
X-RateLimit-Limit	Limite da janela (req/minuto)
X-RateLimit-Remaining	Quantas chamadas você ainda pode fazer nessa janela
X-RateLimit-Reset	Unix timestamp quando a janela reseta
X-RateLimit-Scope	Qual camada está mais próxima do limite: ip, tenant, endpoint

Resposta 429

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

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Limite de 100 req/minuto no scoring atingido. Tente novamente em 23s.",
    "details": {
      "limit": 100,
      "scope": "endpoint:transactions/analyze",
      "retry_after_seconds": 23
    },
    "request_id": "req_01HVZX…"
  }
}

Boas práticas

1. Use Idempotency-Key para retries seguros

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

Mesmo que retry caia em 429, o servidor reconhece a chave e não cobra duas vezes.

2. Respeite Retry-After

Não chute o backoff: use o header. O servidor sabe melhor.

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 localmente para leitura

Recursos que mudam pouco (lista de assets, configuração de regras) podem ser cacheados por 5-10 minutos. Os endpoints retornam Cache-Control: max-age=300 e ETag.

Recursos de leitura idempotentes podem ser cacheados localmente pelo seu serviço; respeite os headers de cache quando presentes.

Aumentar limite

Se precisar de mais throughput:

1. Upgrade de plano (self-service no console)
2. Para enterprise/spikes pontuais: dev-support@sentinexrisk.com com (a) RPS desejado, (b) janela de pico, (c) justificativa
3. SLA de resposta para uplift: < 4h úteis

Métricas observáveis pelo cliente

No console Settings → Usage:

• Throughput atual vs limite (gráfico 7d)
• Top 10 endpoints mais usados
• Histórico de 429 nas últimas 24h
• Alertas configuráveis (ex: notificar Slack se atingir 80% do plano)