Pular para o conteúdo principal

Rate Limits

A API aplica um limite global por integrador nas rotas públicas /v1/* do originador, para proteger contra abuso.

Limite padrão​

  • 120 requisições por minuto, por X-Client-Id (com fallback para o IP de origem), em janela deslizante de 1 minuto.
  • O limite vale para as rotas de integração /v1/* do originador. Não se aplica a:
    • POST /v1/auth/login e POST /v1/auth/token (autenticação)
    • /v1/health, /v1/openapi.json, /v1/.well-known/jwks.json
    • rotas internas (Backoffice, Portal, Starkbank, migração)

Headers de rate limit​

Toda resposta das rotas limitadas inclui:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 95

Resposta 429​

Ao exceder o limite, a API responde 429 com o header Retry-After (segundos até liberar) e o corpo:

{
  "detail": "rate_limit_exceeded",
  "retry_after_seconds": 30
}
Boas práticas

Respeite o Retry-After antes de retentar e use backoff exponencial em falhas consecutivas. Precisa de um limite maior? Fale com o Backoffice Zemo.