Merchant API errors

When a Merchant API call fails, the response combines an HTTP status code with a JSON body that explains the problem. This page lists the status semantics, the error shape, and how to retry safely.

Since API v1.15, failed requests return a status code specific to the failure instead of a generic response — see API versions and changelog.

HTTP status codes#

The documented rate limit surfaces as 405 followed by 403 while the limit stays exceeded; if you ever receive 429, treat it the same way. Details: Merchant API rate limits.

Error response shape#

Failed calls return a JSON body with a status field and a human-readable explanation, typically in a message field:

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

Successful calls return "status": "success" plus a data array. Evaluate the HTTP status code first, then the body. Message texts are not part of the API contract — branch on status codes, never on message strings.

Retry guidance#

A proven starting point: initial delay 500 ms, doubling per attempt, random jitter of up to 300 ms, maximum delay 30 s, at most 5 attempts. Make retried operations idempotent in your own system, for example by deduplicating on 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"

Diagnose authentication failures#

• Run the SignatureCheck smoke test to separate credential problems from endpoint problems.
• Verify that the instance name matches the subdomain of your payment page.
• In signature mode, compare your query-string encoding with the reference implementation in Merchant API authentication.

Logging best practices#

• Log HTTP status, resource path and your correlation ID (for example referenceId) — never the API secret or ApiSignature.
• Separate validation errors from authentication errors in your metrics.
• Prefer webhooks over aggressive polling so transient errors have less impact.