Integration

Erreurs

Toutes les erreurs partagent la meme enveloppe et portent un request_id exploitable dans les API Logs.

Enveloppe

{
  "error": {
    "type": "validation_error",
    "code": "invalid_parameters",
    "message": "La requete contient des parametres invalides.",
    "fields": [
      { "field": "amount", "message": "Le montant doit etre superieur a zero." },
      { "field": "currency", "message": "Devise non supportee : ZZZ." }
    ],
    "doc_url": "/docs/errors"
  },
  "request_id": "req_7k2m9dqz3x"
}

Types d’erreur

Parametre	Type	Description
`authentication_error`	401	Cle API absente, invalide ou revoquee.
`authorization_error`	403	Droits insuffisants — cle publique en ecriture, compte suspendu, role trop faible.
`invalid_request_error`	400	Requete malformee (JSON invalide, corps non objet).
`validation_error`	422	Parametres invalides. Le detail est dans fields[].
`idempotency_error`	409	Cle d’idempotence reutilisee avec des parametres differents, ou requete en cours.
`rate_limit_error`	429	Trop de requetes sur la fenetre courante.
`not_found_error`	404	Ressource inexistante ou hors de votre tenant.
`conflict_error`	409	Operation incompatible avec l’etat courant (annuler un paiement deja reussi).
`connection_error`	422 / 502	Aucune connexion disponible, ou connexion indisponible.
`payment_error`	422	Le paiement a ete refuse.
`insufficient_funds_error`	422	Solde marchand insuffisant pour un payout ou un remboursement.
`api_error`	500	Erreur interne. Reessayez avec un backoff.

Codes d’echec de transaction

Lorsqu’un paiement ou un payout echoue, l’objet porte un champ failure normalise, independant du reseau utilise.

Code	Signification
`insufficient_funds`	Le solde du compte client est insuffisant.
`customer_declined`	Le client a refuse l’autorisation.
`authorization_timeout`	Aucune confirmation dans le delai imparti.
`network_error`	Le reseau de paiement est temporairement indisponible.
`cancelled_by_customer`	Paiement annule par le client.
`cancelled_by_merchant`	Paiement annule par le marchand.
`invalid_account`	Compte destinataire invalide ou inexistant.
`card_declined`	Carte refusee par l’emetteur.

Bonnes pratiques

Journalisez toujours le request_id : il permet de retrouver l’appel exact dans Developers → API Logs.
Ne rejouez pas les erreurs 4xx sans corriger la requete — sauf 429, a rejouer apres Retry-After.
Rejouez les 5xx avec un backoff exponentiel et la meme Idempotency-Key : aucune transaction en double ne sera creee.
Un echec de transaction (failure) n’est pas une erreur HTTP : la requete a reussi, c’est le paiement qui a echoue.