Rate Limiting

A BSPAY aplica rate limiting por endpoint e bloqueio anti-abuso por credencial. Excedê-los retorna 429 Too Many Requests.

Limites por endpoint

Bloqueio anti-abuso

Independente do rate limit por endpoint, há um bloqueio global por erros consecutivos:

A ideia é proteger contra:

• Brute-force de credenciais (/oauth/token)
• Enumeração de username ou chaves PIX

Resposta 429

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Try again later.",
    "group": "SECURITY",
    "retryable": true,
    "details": {
      "retry_after_seconds": 12
    }
  }
}

Headers de resposta

Toda resposta (sucesso ou erro) inclui:

Boas práticas

1. Cache do access token

Token tem validade de 1h — não regenere a cada request.

import time

class TokenCache:
    def __init__(self):
        self.token = None
        self.expires_at = 0

    def get(self):
        if self.token and time.time() < self.expires_at - 60:
            return self.token
        self.token = self._fetch_new()
        self.expires_at = time.time() + 3600
        return self.token

let cached = { token: null, expiresAt: 0 };

async function getToken() {
  if (cached.token && Date.now() / 1000 < cached.expiresAt - 60) {
    return cached.token;
  }
  cached.token = await fetchNewToken();
  cached.expiresAt = Date.now() / 1000 + 3600;
  return cached.token;
}

2. Retry com backoff exponencial

Em 429, respeite Retry-After antes de retentar. Para 502/503, use backoff exponencial (1s → 2s → 4s → 8s).

import time, requests

def with_retry(method, url, max_retries=4, **kwargs):
    for attempt in range(max_retries):
        res = requests.request(method, url, **kwargs)

        if res.status_code == 429:
            wait = int(res.headers.get('Retry-After', 2 ** attempt))
            time.sleep(wait)
            continue

        if res.status_code in (502, 503):
            time.sleep(2 ** attempt)
            continue

        return res

    raise Exception("max_retries exceeded")

3. Webhook em vez de polling

Polling em transactions/list desperdiça quota. Configure postback_url e reaja ao webhook cashin.confirmed / cashout.confirmed. Reconcile via list só periodicamente (1×/hora).

4. Nonce + idempotência em rotas com HMAC

X-Nonce deve ser único nos últimos 5 min. Se quiser retry seguro:

• Mesmo external_id + mesmo body + nonce novo → idempotente (segunda chamada retorna a transação original)
• Mesmo external_id + body diferente → erro DUPLICATE_EXTERNAL_ID

Erros relacionados