error handling

Il existe quatre indicateurs distincts. Lisez les quatre lorsqu’ils sont présents :

1. Statut HTTP — résultat du transport/de l’API.

2. responseCode et success de l’enveloppe externe — résultat de l’opération au niveau de la plateforme.

3. data.code ou data.responseCode imbriqué dans la transaction — résultat du provider/de la transaction.

4. status de la transaction — état du cycle de vie et principal indicateur de règlement.

Référence des statuts HTTP

Statut HTTP	Signification dans les API marchand	Action
200 OK	La requête a été traitée. Pour les opérations financières, inspectez le code/statut imbriqué.	Analysez le body ; ne supposez pas qu’un paiement a réussi uniquement parce que le statut HTTP est 200.
400 Bad Request	Échec de validation, configuration, règle métier, wallet, provider ou référence inconnue.	Corrigez les erreurs d’entrée déterministes. En cas d’incertitude financière, vérifiez le statut avant de réessayer.
401 Unauthorized	Token bearer manquant/expiré/invalide, mauvais rôle, identifiants de connexion invalides ou identité dashboard non reconnue.	Renouvelez le token local une seule fois. Si la connexion elle-même renvoie 401, corrigez les identifiants ou l’état du compte.
403 Forbidden	Verrouillage de connexion, service marchand désactivé ou rejet par la liste blanche IP du service.	Attendez la fin du verrouillage ; sinon utilisez une IP source autorisée ou demandez l’activation du service.
404 Not Found	Chemin incorrect ou version d’API non prise en charge.	Corrigez l’URL ; ne réessayez pas sans modification.
405 Method Not Allowed	Chemin correct mais mauvais verbe HTTP.	Utilisez la méthode documentée ici.
415 Unsupported Media Type	Le body de la requête n’a pas été envoyé en JSON.	Envoyez Content-Type: application/json.
500 Internal Server Error	Échec inattendu du traitement serveur/provider.	Considérez le résultat financier comme inconnu et recherchez par transRef ; réessayez les appels non financiers avec backoff.

Les endpoints marchand ne renvoient normalement pas HTTP 201 ou 409. Un data.code imbriqué égal à 201 pour une collecte signifie que le provider a accepté la requête et qu’elle est en attente ; il ne s’agit pas d’un statut HTTP.

Structures de réponse de la plateforme

Enveloppe d’échec métier

{
  "data": null,
  "message": "Payment reference already exists",
  "success": false,
  "responseCode": "400"
}

Réponse de validation ou d’exception

Certains échecs se produisent avant que le contrôleur ne crée l’enveloppe standard et ne contiennent que deux champs :

{
  "responseCode": "400",
  "message": "The amount field is required"
}

Votre parseur d’erreurs doit accepter les deux formats et doit également tolérer un body d’erreur non JSON provenant de la couche de sécurité ou de la gateway.

Référence des codes plateforme et transaction

Code	Emplacement	Signification	Action
00	Enveloppe externe	L’opération API a réussi.	Continuez à inspecter le statut financier imbriqué.
400	Enveloppe externe/réponse d’erreur	L’opération API a échoué pendant la validation ou le traitement métier.	Inspectez message ; corrigez ou rapprochez selon les indications ci-dessous.
401	Réponse de connexion/d’erreur	Identifiants invalides, compte inactif, incohérence d’intégrité ou contexte de sécurité invalide.	Renouvelez/corrigez les identifiants une seule fois ; ne bouclez pas.
403	Réponse de connexion/sécurité	Compte verrouillé, service indisponible ou IP source rejetée.	Attendez ou corrigez la configuration marchand/service/IP.
500	Réponse d’erreur	Échec interne inattendu.	Rapprochez les requêtes financières à l’aide de leur référence avant toute nouvelle tentative.
201	data.code d’une collecte	Le provider a accepté la requête et elle est en attente.	Suivez les instructions de continuation et interrogez le statut.
01	Code de réponse de transaction enregistré	Collecte en attente acceptée par un provider.	Interrogez le statut.
00 ou 0	data.code d’une collecte	Le provider indique une réussite immédiate.	Rapprochez avec le statut/reporting.
96	Code de transaction enregistré/provider	Échec du traitement local ou de l’appel provider.	Vérifiez le statut de la transaction et l’annulation du wallet ; ne réessayez pas aveuglément.
Toute autre valeur	Code provider/transaction imbriqué	Résultat spécifique au provider. L’ensemble des codes provider est ouvert.	Conservez le code/message exact et utilisez status comme autorité sur le cycle de vie.

Comme les opérateurs peuvent renvoyer de nouveaux codes propres aux providers, aucun document marchand figé ne peut lister tous les codes provider imbriqués. Implémentez une gestion des codes inconnus : journalisez-les, ne les mappez pas à une réussite et interrogez le statut de la transaction.

Erreurs déterministes d’entrée et de configuration

Ces erreurs peuvent être corrigées avant un nouvel envoi. Utilisez une nouvelle référence uniquement lorsque la requête précédente a été définitivement rejetée avant la création de la transaction ; vérifier le statut en premier reste l’approche la plus sûre.

Message	Signification	Action
The amount field is required	amount est nul ou vide.	Envoyez une chaîne décimale.
Request amount is invalid / Deposit amount is invalid	Le montant ne peut pas être interprété pour un provider limité.	Supprimez les séparateurs/symboles et envoyez une chaîne décimale positive.
Request/Deposit amount is below... ou exceeds...	Le minimum/maximum du provider n’a pas été respecté.	Ajustez le montant à la plage indiquée.
The transaction reference field is required	transRef est manquant.	Générez et conservez une référence.
Payment reference already exists	La référence de collecte a déjà été utilisée.	Interrogez le statut ; ne soumettez pas l’opération comme un nouveau paiement.
Transaction exist with the specified transaction reference	La référence de transfert/facture a déjà été utilisée.	Interrogez le statut ; ne soumettez pas l’opération comme un nouveau paiement.
Account number or Msisdn is required	Les deux identifiants de destination sont nuls.	Envoyez l’identifiant exigé par customerIdentificationType.
Country code field is required	countryCode est manquant.	Utilisez la valeur issue de la découverte.
OperatorId is required / Operator Id is required	operatorId est manquant.	Utilisez la valeur issue de la découverte.
No provider found / Operator not found	L’opérateur n’est pas configuré pour le parcours demandé.	Rafraîchissez la découverte et corrigez la combinaison pays/opérateur.
Currency code is required...	La devise requise est absente.	Envoyez toujours la devise découverte.
The specified currency is not supported for the selected country	Le mapping pays/devise est invalide.	Sélectionnez une devise retournée pour ce pays.
Product code is required	Le provider sélectionné exige un code produit/banque.	Obtenez-le via la découverte des produits.
Account number is required / Account name is required / Narration is required	Le provider de transfert sélectionné exige ces champs.	Effectuez la recherche de nom et envoyez les détails de destination validés ainsi que le motif.
Product configuration could not be resolved for this transaction	Aucun produit ne correspond à l’opération/devise.	Arrêtez le parcours et demandez une vérification de la configuration.
Fee configuration could not be resolved for this transaction	La tarification du produit est absente ou invalide.	Arrêtez le parcours et demandez une vérification de la configuration.
Transaction exceeds the configured single transaction limit	La limite par transaction du produit est dépassée.	Réduisez le montant ou ne fractionnez que si les règles métier autorisent des paiements séparés.
Daily transaction count limit exceeded	La fréquence quotidienne autorisée pour le produit est atteinte.	Attendez le prochain jour UTC ou demandez une révision de la limite.
Daily transaction amount limit exceeded	La limite quotidienne de valeur du produit est atteinte.	Attendez le prochain jour UTC ou demandez une révision de la limite.
Insufficient funds in merchant wallet	Le wallet de débit ne peut pas couvrir la transaction et les frais applicables.	Approvisionnez le wallet correspondant à l’environnement et à la devise, puis vérifiez le solde.
No wallet is configured for this transaction currency. Please contact support	Aucun wallet ou chemin de conversion utilisable n’existe.	Arrêtez et demandez la configuration du wallet ; changer la référence ne résoudra pas le problème.
No dedicated wallet is configured for this provider and currency. Please contact support	L’opérateur exige un wallet dédié qui n’existe pas.	Arrêtez et demandez la configuration du wallet.

Erreurs transitoires ou d’intégrité

Message	Signification	Action
Service not available	Le service marchand requis n’est pas activé.	Demandez son activation ; ne réessayez pas continuellement.
IP address not allowed	La liste blanche d’IP du service a rejeté l’appelant.	Utilisez une IP de sortie stable et enregistrée.
Merchant wallet provisioning is busy. Please retry	Une autre requête est en train de créer le même wallet de collecte.	Réessayez avec un court backoff aléatoire, en conservant la même référence métier après rapprochement du statut.
Transaction processing is busy. Please retry	Un autre processus détient le verrou de transaction/wallet.	Interrogez le statut, puis ne réessayez que si la transaction n’est pas déjà en cours.
Wallet checksum validation failed	La validation d’intégrité du wallet a échoué.	Arrêtez les transactions sur ce wallet et escaladez ; ne réessayez pas.
Wallet environment validation failed	Les environnements du wallet et du marchand ne correspondent pas.	Arrêtez et demandez une vérification de l’environnement/du wallet.
Provider invocation failed.	Le provider a renvoyé un résultat non-2xx après le traitement local ; une annulation a été tentée.	Vérifiez le statut et l’historique du wallet avant toute nouvelle tentative.
Unable to confirm transaction status...	Le statut du provider n’a pas pu être obtenu.	Conservez la référence d’origine et continuez le polling avec backoff.
Transaction requires admin reversal review	Le résultat provider est incertain et une annulation automatique n’est pas sûre.	N’exécutez pas et ne réessayez pas le paiement ; surveillez le statut et escaladez via le support marchand.
Internal server error	Erreur API non gérée.	Considérez le résultat financier comme inconnu et rapprochez-le par référence.

Exemple de pseudocode de gestion des erreurs

send(request)
  if HTTP 200:
    if outer responseCode != "00":
      handle platform failure
    else if financial request:
      inspect nested code/status
      persist transRef and providerReference
      poll when status is not final
  else if HTTP 401:
    refresh token once and retry only the authenticated API call
  else if HTTP 400:
    inspect message
    for financial requests, query status before resubmitting
  else if HTTP 403:
    stop; resolve lock, service access, or IP whitelist
  else if timeout or HTTP 500:
    mark financial outcome UNKNOWN
    query status using the original transRef