Rate limit della Merchant API

Per garantire un uso equo delle risorse, la Merchant API applica un rate limit a tutte le request.

Limite

Campo | Valore
Soglia | 600 request ogni 5 minuti
Enforcement | AWS WAF

Non inventare soglie diverse da quelle documentate nella fonte API Reference. Se FlowAlp pubblica limiti white-label diversi, aggiorna questa pagina.

TODO FlowAlp: confermare che il rate limit white-label coincide con quello documentato (600 / 5 min via AWS WAF).

Cosa succede se superi il limite

Status | Significato | Azione consigliata
405 Method Not Allowed | Spesso primo segnale di blocco WAF per rate limit | Attendi e ritenta con backoff
403 Forbidden | Blocco successivo del WAF | Non insiste in loop stretto; aumenta il delay

Questi status possono avere anche altre cause (metodo non consentito, autorizzazione). Correla con volume di traffico e timestamp.

Best practice

• Retry con exponential backoff — after 405/403 sospetti di rate limit, ritenta con delay crescente.
• Riduci le request — aggrega operazioni quando l'API lo consente; evita polling aggressivo.
• Verifica webhook-first — preferisci webhook a polling continuo dello stato pagamento.
• Monitora — registra status code e latency senza loggare segreti.

Esempio di backoff (Node.js)

# javascript
async function withBackoff(fn, { maxAttempts = 5, baseMs = 500 } = {}) {
  let attempt = 0;
  for (;;) {
    attempt += 1;
    try {
      return await fn();
    } catch (err) {
      const status = err.status;
      const retriable = status === 405 || status === 403;
      if (!retriable || attempt >= maxAttempts) {
        throw err;
      }
      const delay = baseMs * 2 ** (attempt - 1);
      await new Promise((r) => setTimeout(r, delay));
    }
  }
}

Passaggi successivi

• Autenticazione (/docs/flowalp-pay/api/authentication)
• Errori (/docs/flowalp-pay/api/errors)

TODO FlowAlp: creare e collegare api/errors