Erreurs

Toutes les erreurs de l’API ont la même forme : un statut HTTP et un objet error.

{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_failed",
    "message": "Le champ amount est obligatoire.",
    "param": "amount",
    "doc_url": "https://docs.mercy-pay.com/developers/errors#validation_failed",
    "request_id": "req_01jc8x4m2v7t9qk3n5w6y8z0ab",
    "errors": {
      "amount": [
        "Le champ amount est obligatoire."
      ]
    }
  }
}

Champ	Contenu
`type`	La famille de l’erreur, voir plus bas
`code`	Un code stable : c’est lui que votre code doit tester
`message`	Une phrase en français pour un humain. Son texte peut changer : ne le comparez jamais
`param`	Le premier champ en cause, ou `null`
`doc_url`	Le lien vers l’explication de ce code sur cette page
`request_id`	L’identifiant de la requête, à nous donner si vous contactez le support

Sur une erreur 422, errors liste chaque champ refusé avec ses messages.

Identifiant de requête

Chaque réponse, réussie ou non, porte un en-tête Request-Id (req_…), et chaque erreur le répète dans error.request_id. Gardez-le dans vos journaux : il désigne l’appel exact, et le support retrouve la requête avec lui.

Types d’erreur

`type`	Quand
`authentication_error`	Clé absente, invalide, compte suspendu ou KYC manquant
`invalid_request_error`	Requête ou données invalides, objet introuvable ou état incompatible
`idempotency_error`	Clé d’idempotence absente, en cours ou réutilisée
`payment_error`	Paiement refusé
`rate_limit_error`	Trop de requêtes
`api_error`	Erreur de notre côté

Codes

Cette liste peut s’enrichir, mais un code existant ne change jamais de nom. Traitez un code inconnu comme une erreur générique de son type.

`api_key_missing`

401 · authentication_error Aucune clé n’accompagne la requête. Ajoutez l’en-tête Authorization: Bearer mp_sandbox_… (ou mp_live_…). Voir Authentification.

`api_key_invalid`

401 · authentication_error La clé est inconnue ou a été révoquée. Copiez une clé active depuis la console développeurs. Vérifiez qu’elle n’a pas d’espace en trop.

`merchant_suspended`

403 · authentication_error Le compte marchand est suspendu. Contactez le support : aucune requête n’aboutit tant que le compte reste suspendu.

`live_mode_requires_kyc`

403 · authentication_error Une clé live est utilisée avant l’approbation de votre vérification d’identité. Terminez votre KYC. En attendant, travaillez avec une clé sandbox.

`forbidden`

403 · authentication_error La clé ne permet pas cette action. Vérifiez l’environnement de la clé et la ressource visée.

`bad_request`

400 · invalid_request_error La requête est mal formée, par exemple un JSON invalide. Envoyez un corps JSON valide avec Content-Type: application/json.

`idempotency_key_missing`

400 · idempotency_error Idempotency-Key manque sur une opération qui l’exige (paiement direct, retrait). Générez une clé unique par opération et envoyez-la dans l’en-tête. Voir Idempotence.

`resource_not_found`

404 · invalid_request_error L’objet n’existe pas, ou appartient à un autre marchand ou à l’autre environnement. Vérifiez l’id et l’environnement de la clé : un objet sandbox n’est pas visible avec une clé live.

`method_not_allowed`

405 · invalid_request_error La méthode HTTP n’est pas acceptée sur cette URL. Consultez la référence de l’endpoint pour la bonne méthode.

`conflict`

409 · invalid_request_error L’action contredit l’état de l’objet : un client avec cet e-mail existe déjà, une session est déjà payée… Lisez message : il dit quoi faire. Pour un client en double, l’id existant est renvoyé dans error.customer.

`idempotency_key_in_use`

409 · idempotency_error Une requête avec la même clé d’idempotence est encore en cours. Attendez quelques secondes puis rejouez la même requête avec la même clé.

`idempotency_key_reused`

409 · idempotency_error La clé d’idempotence a déjà servi pour une requête au contenu différent. Utilisez une nouvelle clé pour une nouvelle opération.

`validation_failed`

422 · invalid_request_error Un ou plusieurs champs sont invalides. error.param nomme le premier champ en cause et errors détaille chacun.

`insufficient_balance`

422 · invalid_request_error Votre solde disponible, retraits déjà réservés déduits, ne couvre pas le remboursement et ses frais. Attendez de nouveaux encaissements, ou annulez un retrait en attente, puis réessayez.

`refund_not_allowed`

422 · invalid_request_error Ce paiement ne peut pas être remboursé : il n’a pas abouti, il date de plus de 90 jours, ses fonds carte ne sont pas encore disponibles, ou l’opérateur du client refuse les remboursements pour le moment. Le message dit laquelle de ces raisons s’applique.

`payment_declined`

422 · payment_error Le paiement a été refusé dès sa création. Proposez au payeur un autre numéro ou un autre moyen de paiement.

`rate_limited`

429 · rate_limit_error Trop de requêtes sur une courte période. Attendez le délai de l’en-tête Retry-After. Voir Limites de débit.

`server_error`

500 · api_error Une erreur s’est produite de notre côté. Réessayez avec la même Idempotency-Key : l’opération ne sera jamais faite deux fois. Si l’erreur persiste, donnez-nous le request_id.

Motif d’échec d’un paiement ou d’un retrait

Un paiement ou un retrait échoué n’est pas une erreur de requête : il porte un failure_code et un failure_reason en français.

`failure_code`	Signification
`insufficient_balance`	Le solde du payeur ne couvre pas le montant
`payment_not_approved`	Le payeur a refusé ou n’a pas validé la demande sur son téléphone
`payer_not_found`	Le numéro n’est pas associé à l’opérateur choisi
`payer_limit_reached`	Le payeur a atteint la limite fixée par son opérateur
`transaction_expired`	Le payeur n’a pas confirmé à temps
`customer_not_eligible`	Le payeur n’a pas accès à ce type de paiement
`invalid_phone_number`	Le numéro n’est pas valide pour l’opérateur
`amount_out_of_bounds`	Le montant sort des limites de l’opérateur
`provider_temporarily_unavailable`	L’opérateur est momentanément indisponible
`recipient_not_found`	Retrait : le numéro du bénéficiaire n’est pas reconnu
`payouts_not_allowed`	Retrait : les retraits ne sont pas activés vers cet opérateur
`unspecified_failure`	Refus sans motif précis

Erreurs métier fréquentes

Message	Cause
`Solde disponible insuffisant pour ce montant.`	Le solde du pays et de l’opérateur ne couvre pas le retrait
`Opérateur Mobile Money invalide pour ce pays.`	Code opérateur incohérent avec le pays
`Cette devise ne figure pas dans la norme ISO 4217.`	Code devise inconnu
`Ce moyen de paiement n'est pas disponible pour le moment.`	Aucun taux de conversion disponible vers la devise de l’opérateur mobile money choisi
`Le montant minimum pour un paiement par carte est de 0.50 USD.`	Montant sous le minimum carte

Introduction

Compte

Paiements

Liens de paiement

Abonnements

Soldes et retraits

Webhooks