Limites de débit Merchant API

La Merchant API applique un quota de requêtes afin d'offrir des performances prévisibles à tous les marchands. Concevez votre intégration pour rester bien en dessous de la limite et ralentir proprement lorsqu'elle est atteinte.

La limite#

Le quota couvre aussi bien les pics que le trafic soutenu : 600 requêtes en cinq minutes correspondent en moyenne à deux requêtes par seconde.

Que se passe-t-il en cas de dépassement#

Ces deux codes surviennent aussi pour d'autres raisons — mauvais verbe HTTP ou permissions manquantes. Ne les traitez comme signaux de rate limit que lorsqu'ils sont corrélés à un volume élevé ; la sémantique complète des statuts se trouve dans Erreurs Merchant API.

Stratégie de backoff#

Réessayez avec un backoff exponentiel et du 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);
}

Réduire votre volume de requêtes#

• Utilisez les webhooks au lieu d'interroger le statut de paiement en boucle.
• Mettez en cache les données qui évoluent lentement, comme la liste des fournisseurs de PaymentProvider.
• Agrégez le travail : récupérez des listes en une seule requête plutôt que les entités une par une.
• Étalez dans le temps les tâches planifiées comme la réconciliation, au lieu de toutes les lancer à l'heure pile.