Erreurs

Quand quelque chose ne va pas, MafPay répond avec un code HTTP (400, 401, 404…) et un corps JSON toujours de la même forme. Lisez le champ message : il est fait pour être compris.

Le format d’une erreur

{
  "status": 400,
  "error": "Bad Request",
  "message": "Orange Money n'accepte que des montants entiers (sans décimales).",
  "timestamp": "2026-09-25T13:34:30.088987+00:00"
}

Champ	Signification
status	Le code HTTP.
error	Son nom en anglais (Bad Request, Unauthorized, Not Found…).
message	L’explication, en clair.
timestamp	L’heure de l’erreur.
errors	(Seulement pour les erreurs de validation) le détail par champ.

Exemple avec détail par champ :

{
  "status": 400,
  "error": "Bad Request",
  "message": "This field is required.",
  "timestamp": "2026-09-25T13:34:17.709235+00:00",
  "errors": { "amount": ["This field is required."] }
}

Les codes

Code	Nom	Ce que ça veut dire	Que faire
201	Created	Paiement créé.	Tout va bien.
200	OK	Requête réussie.	Tout va bien.
400	Bad Request	Votre requête est incorrecte : champ manquant ou mauvais format, provider inconnu ou non activé, montant décimal avec Orange Money, refus de l’opérateur…	Lisez message et errors, corrigez la requête. Ne réessayez pas telle quelle.
401	Unauthorized	Clés absentes ou invalides, application suspendue, ou clés d’un mauvais mode.	Voir Authentification.
403	Forbidden	Action interdite (ex : clés live pour simuler un webhook sandbox).	Utilisez les bonnes clés / le bon environnement.
404	Not Found	Paiement introuvable (mauvaise référence, ou paiement d’une autre application / de l’autre mode).	Vérifiez la reference et vos clés.
429	Too Many Requests	Trop de requêtes en peu de temps.	Attendez quelques secondes puis réessayez (Limites).
5xx	Erreur serveur	Un problème côté MafPay.	Réessayez après un court délai ; si ça persiste, contactez le support avec la reference et l’heure.

Les messages les plus fréquents

Message (extrait)	Cause	Solution
« Clés API invalides. »	Clé ou secret faux, autre entreprise, ou application suspendue.	Recopiez les clés du portail ; vérifiez l’endpoint_key.
« Cette application n’est pas en mode live : utilisez vos clés sandbox (pk_test_…). »	Vous utilisez des clés _live_ alors que l’application est en sandbox.	Utilisez pk_test_… ou passez l’application en live.
« Cette application est en mode live : utilisez vos clés live (pk_live_…). »	Vous utilisez des clés _test_ sur une application déjà en live.	Utilisez pk_live_…, ou une application de test dédiée.
« Échec d’initiation du paiement Wave : Identifiants sandbox invalides (Clé API)… »	Les identifiants du moyen de paiement ne sont pas les valeurs de test du sandbox.	Saisissez les valeurs de test dans l’onglet Sandbox.
« Provider non supporté : XX. Providers disponibles : ORANGE_MONEY_SN, WAVE_SN. »	Le code provider n’existe pas.	Utilisez un code de la liste (Moyens de paiement).
« Orange Money n’accepte que des montants entiers (sans décimales). »	amount décimal avec Orange Money.	Envoyez "2500" et non "2500.50".
« Transaction introuvable. »	Référence inexistante ou d’un autre environnement.	Vérifiez la référence et que vos clés sont du même mode que le paiement.
« This field is required. » (avec errors)	Champ obligatoire absent (souvent provider ou amount).	Ajoutez le champ indiqué dans errors.

Gérer les erreurs dans votre code

Le principe : toujours vérifier le code de retour avant d’utiliser la réponse.

const response = await fetch(url, options);
const body = await response.json();

if (!response.ok) {
  // body.message est lisible ; body.errors (facultatif) détaille par champ
  console.error(`MafPay ${response.status} : ${body.message}`, body.errors ?? "");
  if (response.status === 429) { /* attendre puis réessayer */ }
  throw new Error(body.message);
}

response = requests.post(url, headers=headers, json=payload, timeout=20)
body = response.json()
if not response.ok:
    print(f"MafPay {response.status_code} : {body['message']}", body.get("errors", ""))
    response.raise_for_status()

Quand réessayer, quand ne pas réessayer

• 429 et 5xx : oui, après une pause (quelques secondes, en augmentant : 2 s, 4 s, 8 s…).
• 400, 401, 403, 404 : non. Réessayer la même requête donnera le même résultat ; corrigez d’abord la cause.
• Timeout / coupure réseau au moment de l’initiation : vous ne savez pas si le paiement a été créé. Ne relancez pas aveuglément (risque de double paiement) : voir la FAQ.