Rate limits

1. Limites por endpoint

Volumes maiores são negociáveis — para integradores com fluxo contínuo de alta escala, fale com o time comercial da IORQ para aumentar limites contratualmente.

2. Modelo de limitação

A IORQ usa token bucket:

• Limite por minuto = taxa de reposição de tokens
• Burst = tamanho máximo do balde — você pode disparar até esse número em sequência
• O balde se reenche linearmente: limit/60 tokens por segundo

Exemplo prático: para POST /loan (120/min, burst 240): você pode disparar 240 chamadas em sequência (consumindo todo o burst), depois fica limitado a 2 req/s (120/60) até o balde reencher.

3. Headers de resposta

Toda resposta inclui headers de inspeção:

HTTP/1.1 200 OK
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1715601260

Use X-RateLimit-Remaining para implementar throttling preditivo — quando cair abaixo de 10% do limite, reduza a vazão sem esperar receber 429.

4. Resposta 429

HTTP/1.1 429 Too Many Requests
Retry-After: 12

{
  "error_code": "rate_limited",
  "message": "Rate limit exceeded for POST /loan. Retry after 12 seconds.",
  "request_id": "req_8a3f2c1b9d4e"
}

Respeite o Retry-After. Disparar de novo antes só consome mais tentativas — a IORQ não relaxa o limite por insistência.

5. Estratégia recomendada

1. Throttling local — limite suas chamadas ao mesmo nível do limite IORQ menos uma folga (ex: 100/min para um limite de 120/min)
2. Fila com vazão controlada — para lotes grandes, enfileire e processe em vazão constante. Evita estourar o burst
3. Backoff exponencial em 429 — comece com Retry-After e dobre a cada nova falha: 12s, 24s, 48s, ...
4. Circuit breaker — após 3 429 consecutivos, pause o cliente por 5 minutos antes de tentar de novo
5. Observabilidade — emita métricas com X-RateLimit-Remaining para detectar tendências de saturação

6. Exceções e isenções

• POST /token tem limite agressivo (10/min) porque tokens devem ser cacheados. Se você está chamando /token 10 vezes/min, sua arquitetura tem bug — confira Autenticação.
• Endpoints de webhook (gerenciamento) têm limite baixo porque são operações administrativas, não de runtime.
• Endpoints GET são mais permissivos — leitura não tem o mesmo custo de escrita.
• Em janelas de pico negociadas (ex: fim de mês), a IORQ pode aumentar limites temporariamente mediante aviso prévio.

7. Próximos passos