Rate limit della Merchant API

La Merchant API applica una quota di richieste per garantire a tutti i merchant prestazioni prevedibili. Progetta l'integrazione per restare ben al di sotto del limite e per rallentare in modo controllato quando lo raggiungi.

Il limite#

La quota copre sia i picchi sia il traffico continuativo: 600 request in cinque minuti corrispondono in media a due richieste al secondo.

Cosa succede se superi il limite#

Entrambi i codici possono avere anche cause diverse — un verbo HTTP errato o permessi mancanti. Trattali come segnali di rate limit solo quando sono correlati a volumi elevati; la semantica completa degli status è in Errori della Merchant API.

Strategia di backoff#

Riprova con exponential backoff e jitter:

async function withBackoff(fn, { maxAttempts = 5, baseMs = 500, maxDelayMs = 30000 } = {}) {
  for (let attempt = 1; ; attempt++) {
    try {
      return await fn();
    } catch (err) {
      const retriable = [403, 405, 429].includes(err.status) || err.status >= 500;
      if (!retriable || attempt >= maxAttempts) {
        throw err;
      }
      const delay =
        Math.min(baseMs * 2 ** (attempt - 1), maxDelayMs) + Math.random() * 300;
      await new Promise((resolve) => setTimeout(resolve, delay));
    }
  }
}

<?php
$delayMs = 500;

for ($attempt = 1; $attempt <= 5; $attempt++) {
    [$status, $body] = sendFlowAlpRequest(); // your HTTP call

    if ($status < 400) {
        break;
    }
    if (!in_array($status, [403, 405, 429], true) && $status < 500) {
        throw new RuntimeException('Non-retriable error: HTTP ' . $status);
    }

    usleep(($delayMs + random_int(0, 300)) * 1000);
    $delayMs = min($delayMs * 2, 30000);
}

Riduci il volume di richieste#

• Usa i webhook invece di interrogare lo stato del pagamento in loop.
• Metti in cache i dati che cambiano lentamente, come la lista dei provider da PaymentProvider.
• Aggrega il lavoro: recupera le liste con una sola richiesta invece di leggere le entità una per una.
• Distribuisci nel tempo i job pianificati, come la riconciliazione, invece di lanciarli tutti allo scoccare dell'ora.