Erreurs & codes de statut

Chaque erreur renvoie la même enveloppe JSON, vous pouvez donc gérer les échecs de façon cohérente sur l'ensemble de l'API.

json

{
  "error": {
    "code": "validation_error",
    "message": "The request payload is invalid.",
    "details": {
      "currency": "No currency matches \"ZZZ\"."
    }
  }
}

Champ	Description
`code`	Un code d'erreur stable et lisible par machine (faites votre `switch` dessus).
`message`	Un résumé lisible par un humain, sûr à journaliser.
`details`	Détail optionnel par champ ou contextuel. Pour les erreurs de validation, les clés sont des noms de champs.

Lisez details, repliez sur message

Pour les 400, affichez les erreurs de champ depuis error.details.<field> ; sinon affichez error.message. Lire un champ de premier niveau sur le corps (au lieu de sous error.details) masque silencieusement de vraies erreurs de validation.

Codes de statut HTTP

Statut	Signification	Cause typique
`200 OK`	Succès	Une lecture ou une action a réussi.
`201 Created`	Créé	Une transaction (ou une autre ressource) a été créée.
`204 No Content`	Succès, corps vide	Une suppression a réussi.
`400 Bad Request`	Erreur de validation / de domaine	Champ manquant/invalide, devise/service inconnu, référence en doublon.
`401 Unauthorized`	Authentification échouée	Jeton manquant, mal formé, expiré ou révoqué ; mauvaise signature de webhook.
`403 Forbidden`	Permission refusée	Le jeton est valide mais le rôle ne peut pas effectuer cette action (p. ex. un non-marchand créant un paiement).
`404 Not Found`	Ressource introuvable	Référence inconnue, ou enregistrement hors de votre périmètre.
`409 Conflict`	Transition d'état invalide	Un changement de statut illégal a été tenté.
`500 Internal Server Error`	Erreur serveur	Échec inattendu — réessayez plus tard ; contactez le support si cela persiste.
`502 Bad Gateway`	Erreur fournisseur	Le fournisseur de paiement en amont a renvoyé une erreur.

Codes d'erreur

`code`	HTTP	Signification & que faire
`validation_error`	400	La charge utile a échoué à la validation. Inspectez `details` pour le(s) champ(s) en cause et corrigez la requête.
`not_found`	404	La ressource n'existe pas ou ne vous appartient pas. Vérifiez la `reference`.
`invalid_state_transition`	409	Un changement de statut illégal a été tenté (les états terminaux sont immuables). Ré-interrogez le statut courant.
`provider_error`	502	Le fournisseur de paiement a échoué. Sûr à réessayer après un court délai ; rapprochez par statut.
`unknown_provider`	400	`provider_code_name` ne correspond à aucun fournisseur enregistré. Omettez-le pour un routage automatique, ou utilisez un code valide.
`webhook_verification_failed`	401	Un webhook fournisseur entrant a échoué à la vérification de signature (rejeté par PayRouter, pas par vous).
`request_error`	4xx	Une erreur de requête générique au niveau du framework (p. ex. auth/permission). Lisez `message`/`details`.
`internal_error`	500	Erreur serveur inattendue. Réessayez ; si cela persiste, contactez le support avec l'horodatage.

Erreurs de validation courantes à la création de paiement

Clé de `details`	Cause	Correctif
`currency`	Code de devise inconnu	Utilisez un code valide (`CDF`, `USD`) ; listez via `GET /api/organization/currency/`.
`service`	Service inconnu	Utilisez un nom/symbole valide (`Vodacom`, `Airtel`, `Orange`, `Africell`).
`merchant`	Aucun profil marchand intégré	Complétez l'intégration sur `/complete-profile`.
`merchant_reference`	Référence en doublon	Utilisez une nouvelle référence unique, ou traitez-la comme déjà soumise.
`amount`	Manquant ou inférieur au minimum	Envoyez une chaîne décimale ≥ `"0.01"`.

Bien gérer les erreurs

Faites un switch sur code, pas sur message (les messages peuvent être localisés ou reformulés).
Réessayez les 502/500 avec un backoff exponentiel ; ne réessayez jamais un 400/403 inchangé.
Journalisez code, message et les reference/merchant_reference de la requête pour le support.

Voir aussi Dépannage pour des correctifs basés sur les symptômes.

Passage en production

Rapports