Merchant API Rate Limits

Die Merchant API wendet ein Anfragekontingent an, damit alle Händler eine vorhersehbare Performance erhalten. Legen Sie Ihre Integration so aus, dass sie deutlich unter dem Limit bleibt und kontrolliert langsamer wird, wenn es erreicht ist.

Das Limit#

Das Kontingent gilt für Lastspitzen ebenso wie für Dauerverkehr: 600 Anfragen in fünf Minuten entsprechen im Schnitt zwei Anfragen pro Sekunde.

Was bei Überschreitung passiert#

Beide Codes treten auch aus anderen Gründen auf — falsches HTTP-Verb oder fehlende Berechtigungen. Werten Sie sie nur dann als Rate-Limit-Signal, wenn sie mit hohem Anfragevolumen korrelieren; die vollständige Status-Semantik steht in Merchant API Fehler.

Backoff-Strategie#

Wiederholen Sie mit exponentiellem Backoff und 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);
}

Anfragevolumen reduzieren#

• Nutzen Sie Webhooks, statt den Zahlungsstatus in einer Schleife abzufragen.
• Cachen Sie sich langsam ändernde Daten wie die Provider-Liste aus PaymentProvider.
• Bündeln Sie Arbeit: Rufen Sie Listen mit einer Anfrage ab, statt Entitäten einzeln zu laden.
• Verteilen Sie geplante Jobs wie die Abstimmung über die Zeit, statt alle zur vollen Stunde zu starten.