Erreurs Merchant API

Lorsqu'un appel Merchant API échoue, la réponse combine un code de statut HTTP et un corps JSON qui explique le problème. Cette page présente la sémantique des statuts, la structure de l'erreur et la bonne façon de réessayer.

Depuis la version v1.15 de l'API, les requêtes en échec renvoient un code de statut spécifique à l'erreur au lieu d'une réponse générique — voir Versions de l'API et changelog.

Codes de statut HTTP#

La limite documentée se manifeste par un 405 suivi d'un 403 tant que la limite reste dépassée ; si vous recevez un jour un 429, traitez-le de la même manière. Détails : Limites de débit Merchant API.

Structure de la réponse d'erreur#

Les appels en échec renvoient un corps JSON avec un champ status et une explication lisible, généralement dans un champ message :

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

Les appels réussis renvoient "status": "success" ainsi qu'un tableau data. Évaluez d'abord le code de statut HTTP, puis le corps. Les textes des messages ne font pas partie du contrat de l'API : basez votre logique sur les codes de statut, jamais sur les chaînes de message.

Conseils de retry#

Un point de départ éprouvé : délai initial de 500 ms, doublement à chaque tentative, jitter aléatoire jusqu'à 300 ms, délai maximal de 30 s, au plus 5 tentatives. Rendez les opérations réessayées idempotentes dans votre système, par exemple en dédupliquant sur 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"

Diagnostiquer les échecs d'authentification#

• Lancez le test rapide SignatureCheck pour distinguer les problèmes d'identifiants des problèmes d'endpoint.
• Vérifiez que le nom d'instance correspond au sous-domaine de votre page de paiement.
• En mode signature, comparez votre encodage de query string avec l'implémentation de référence dans Authentification Merchant API.

Bonnes pratiques de journalisation#

• Journalisez le statut HTTP, le chemin de la ressource et votre identifiant de corrélation (par exemple referenceId) — jamais l'API Secret ni ApiSignature.
• Séparez les erreurs de validation des erreurs d'authentification dans vos métriques.
• Préférez les webhooks au polling agressif afin que les erreurs transitoires aient moins d'impact.