Recursos

Rate Limits

Limites de requests por minuto por API key. Protege a infraestrutura e garante que ninguém afeta o serviço dos outros clientes.

Limites atuais

Endpoint	Limite	Por que
Global (todas as rotas)	1.000/min	Default — overhead de cada cliente
`POST /v1/withdrawals`	100/min	Endpoint mais sensível (cash-out)
`POST /v1/deposits`	200/min	Gerar QR Code é mais frequente

ⓘ

Os limites são por API key, não por IP. Se você tem múltiplas keys (diferentes microsserviços), cada uma tem seu contador independente.

Headers retornados

Toda response inclui:

Header	Significado
`X-RateLimit-Limit`	Limite máximo na janela atual
`X-RateLimit-Remaining`	Quantas requests restam
`X-RateLimit-Reset`	Segundos até resetar a janela

Quando ultrapassar

Você recebe HTTP 429 Too Many Requests com:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 60

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Muitas requests em sequência. Tente novamente em alguns segundos."
  }
}

Boas práticas

Implemente backoff exponencial em retries: 1s → 2s → 4s → 8s → 16s. Não fica no loop apertado batendo 429.
Use X-RateLimit-Remaining pra antecipar — se restam menos de 10, já reduz o ritmo do seu app.
Para batch processing (mandar muitos PIX), use o intervalo natural: 100/min = 1 PIX a cada 600ms. Espalhe ao longo do tempo.
Se precisar de limites maiores, fala com a gente: hiago@realfy.io. Aumentamos pra clientes com volume real comprovado.

⚠

Burst protection

Além do limite por minuto, temos proteção contra burst (rajada): no máximo 20 requests consecutivas em < 1 segundo. Acima disso, mesmo dentro do limite/min, retorna 429.