FlowAlp

Errori della Merchant API

July 30, 2026

Status HTTP della Merchant API FlowAlp Pay, struttura del body JSON di errore e indicazioni pratiche di retry con exponential backoff.

Quando una chiamata alla Merchant API fallisce, la risposta combina uno status HTTP con un body JSON che spiega il problema. Questa pagina elenca la semantica degli status, la struttura dell'errore e come fare retry in sicurezza.

Dalla versione v1.15, le richieste fallite restituiscono uno status specifico per il tipo di errore invece di una risposta generica — vedi Versioni API e changelog.

Status HTTP

StatusSignificatoCosa fare
200 OKRichiesta elaborata; controlla il campo status nel bodyProsegui il flusso
400 Bad RequestRequest malformata o non valida (campi, tipi, encoding)Correggi il payload; non ripetere la richiesta invariata
401 UnauthorizedCredenziali mancanti o non valideVerifica API Secret e metodo di autenticazione; non riprovare invariata
403 ForbiddenAccesso negato; arriva anche dopo un sovraccarico prolungato sull'edge della piattaformaVerifica permessi e instance; con volumi alti fai backoff e riprova
404 Not FoundRisorsa, ID o path sconosciutiControlla Object, id e segmento di versione
405 Method Not AllowedVerbo HTTP errato; sotto carico è anche un primo segnale di rate limitControlla la mappatura dei verbi; con volumi alti fai backoff
429 Too Many RequestsStatus standard di rate limitFai backoff e riprova più tardi
5xxProblema temporaneo lato serverRiprova con exponential backoff

Il rate limit documentato si manifesta come 405 seguito da 403 finché il limite resta superato; se dovessi ricevere 429, trattalo allo stesso modo. Dettagli: Rate limit della Merchant API.

Struttura della risposta di errore

Le chiamate fallite restituiscono un body JSON con un campo status e una spiegazione leggibile, tipicamente nel campo message:

Body di errore tipicoJSON
{
  "status": "error",
  "message": "Description of what went wrong"
}

Le chiamate riuscite restituiscono "status": "success" più un array data. Valuta prima lo status HTTP, poi il body. I testi dei messaggi non fanno parte del contratto dell'API: basa la logica sugli status code, mai sulle stringhe dei messaggi.

Indicazioni per i retry

Classe di erroreRetry?Come
400 / 401 / 404 — errori di validazione e autenticazioneNoCorreggi prima la request o le credenziali
405 / 403 con volumi alti, 429SìExponential backoff con jitter
5xx e timeout di reteSìExponential backoff; limita i tentativi

Un punto di partenza collaudato: ritardo iniziale 500 ms, raddoppio a ogni tentativo, jitter casuale fino a 300 ms, ritardo massimo 30 s, al massimo 5 tentativi. Rendi idempotenti le operazioni ripetute nel tuo sistema, ad esempio deduplicando su referenceId.

Helper PHP di retry con backoffPHP
<?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);
    }
}
Ispezionare status e body con curlbash
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"

Diagnosi dei problemi di autenticazione

  • Esegui lo smoke test SignatureCheck per separare i problemi di credenziali da quelli di endpoint.
  • Verifica che l'instance name corrisponda al sottodominio della tua pagina di pagamento.
  • In modalità firma, confronta l'encoding della query string con l'implementazione di riferimento in Autenticazione della Merchant API.

Best practice di logging

  • Registra status HTTP, path della risorsa e il tuo ID di correlazione (ad esempio referenceId) — mai l'API Secret o ApiSignature.
  • Separa gli errori di validazione da quelli di autenticazione nelle metriche.
  • Preferisci i webhook al polling aggressivo, così gli errori transitori pesano meno.

Correlati: Rate limit della Merchant API, Formato delle request, Prima richiesta API.