Merchant API Fehler

Schlägt ein Merchant-API-Aufruf fehl, kombiniert die Antwort einen HTTP-Statuscode mit einem JSON-Body, der das Problem erklärt. Diese Seite beschreibt die Status-Semantik, den Aufbau der Fehlerantwort und sichere Retries.

Seit API v1.15 liefern fehlgeschlagene Anfragen einen für den Fehler spezifischen Statuscode statt einer generischen Antwort — siehe API-Versionen und Changelog.

HTTP-Statuscodes#

Das dokumentierte Rate-Limit zeigt sich als 405 gefolgt von 403, solange das Limit überschritten bleibt; sollten Sie je 429 erhalten, behandeln Sie es genauso. Details: Merchant API Rate Limits.

Aufbau der Fehlerantwort#

Fehlgeschlagene Aufrufe liefern einen JSON-Body mit einem status-Feld und einer lesbaren Erklärung, typischerweise im Feld message:

{
  "status": "error",
  "message": "Description of what went wrong"
}

Erfolgreiche Aufrufe liefern "status": "success" plus ein data-Array. Werten Sie zuerst den HTTP-Status aus, dann den Body. Meldungstexte sind nicht Teil des API-Vertrags — verzweigen Sie auf Statuscodes, nie auf Meldungs-Strings.

Retry-Empfehlungen#

Ein bewährter Ausgangspunkt: Startverzögerung 500 ms, Verdopplung pro Versuch, zufälliger Jitter bis 300 ms, maximale Verzögerung 30 s, höchstens 5 Versuche. Machen Sie wiederholte Operationen in Ihrem System idempotent, etwa durch Deduplizierung über referenceId.

<?php
function callWithBackoff(callable $request, int $maxAttempts = 5)
{
    $delayMs = 500;

    for ($attempt = 1; $attempt <= $maxAttempts; $attempt++) {
        [$status, $body] = $request();

        if ($status < 400) {
            return $body;
        }

        $retriable = in_array($status, [403, 405, 429], true) || $status >= 500;
        if (!$retriable || $attempt === $maxAttempts) {
            throw new RuntimeException('FlowAlp Pay request failed: HTTP ' . $status);
        }

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

response=$(curl --silent --write-out "\n%{http_code}" \
  --url "https://api.pay.flowalp.com/v1.16/Transaction/<transaction-id>/?instance=<instance>" \
  --header "x-api-key: <api-secret>")

body=$(printf '%s' "$response" | head -n -1)
status=$(printf '%s' "$response" | tail -n 1)

echo "HTTP $status"
echo "$body"

Authentifizierungsfehler eingrenzen#

• Führen Sie den SignatureCheck-Smoke-Test aus, um Zugangsdaten-Probleme von Endpoint-Problemen zu trennen.
• Prüfen Sie, ob der Instance-Name der Subdomain Ihrer Zahlungsseite entspricht.
• Vergleichen Sie im Signaturmodus Ihre Query-String-Kodierung mit der Referenzimplementierung in Merchant API Authentifizierung.

Logging-Empfehlungen#

• Protokollieren Sie HTTP-Status, Ressourcenpfad und Ihre Korrelations-ID (zum Beispiel referenceId) — nie das API Secret oder ApiSignature.
• Trennen Sie Validierungsfehler von Authentifizierungsfehlern in Ihren Metriken.
• Bevorzugen Sie Webhooks gegenüber aggressivem Polling, damit vorübergehende Fehler weniger ins Gewicht fallen.