Erreurs

Toute réponse non-2xx partage la même enveloppe. code est stable entre versions — testez-le côté client plutôt que le message (texte, susceptible de changer).

JSON

{ "code": "invalid_amount", "message": "Montant invalide." }

Authentification#

Code	HTTP	Explication
`missing_api_credentials`	401	En-têtes `X-Api-Key` ou `X-Api-Secret` absents.
`invalid_api_key`	401	Clé inconnue, révoquée, ou secret incorrect (même réponse — on ne révèle pas lequel).
`insufficient_scope`	403	La clé n'a pas le scope requis (ex. `disbursements.write`).
`missing_token` / `invalid_token`	401	Session marchand (dashboard) absente ou invalide.
`live_not_enabled`	403	Mode `live` demandé sur un compte non encore validé (KYB).

Validation (création)#

Code	HTTP	Explication
`invalid_body`	400	JSON malformé.
`invalid_amount`	400	`amount` absent ou ≤ 0.
`currency_mismatch`	400	Devise ≠ celle du compte de reversement.
`invalid_redirect_url`	400	`redirect_url` n'est pas une URL http(s).
`invalid_webhook_url`	400	`webhook_url` n'est pas une URL http(s).
`invalid_customer_tag`	400	`customer_tag` fourni mais introuvable.
`invalid_environment`	400	`environment` ≠ `test`/`live`.
`invalid_interval`	400	`interval` ≠ `weekly`/`monthly`/`yearly`.
`invalid_max_cycles`	400	`max_cycles` ≤ 0.
`invalid_recurrence`	400	`recurrence` ≠ `once`/`weekly`/`monthly`.
`invalid_start_at`	400	`start_at` n'est pas une date ISO‑8601.
`invalid_items`	400	Liste vide, > 500 lignes, ou une ligne sans `recipient`/`amount`.
`missing_recipient`	400	Bénéficiaire absent (versement).
`title_required`	400	Titre du produit facturier absent.
`lookup_url_required`	400	`lookup_url` requis pour un produit `lookup`.
`lookup_url_must_be_https`	400	`lookup_url` doit être en HTTPS.
`invalid_amount_mode`	400	`amount_mode` ≠ `fixed`/`user`/`lookup`.
`invalid_schema_json`	400	Schéma produit invalide ou non conforme.
`invalid_slug`	400	Slug vide ou invalide.

Charges#

Code	HTTP	Explication
`charge_not_found`	404	Token inconnu ou n'appartenant pas au marchand.
`wrong_customer`	403	Charge ciblée : le payeur n'est pas le client désigné.
`charge_expired`	409	La charge a dépassé son échéance.
`charge_not_payable`	409	Charge déjà réglée, expirée ou annulée.
`charge_not_cancelable`	409	Charge déjà payée / expirée / annulée.
`charge_not_refundable`	409	Charge non payée, déjà remboursée, ou déjà reversée.
`charge_not_paid`	409	Renvoi de webhook demandé sur une charge non payée.
`no_webhook_url`	422	Renvoi de webhook : aucune URL configurée.
`webhook_delivery_failed`	502	Votre endpoint n'a pas répondu 2xx au renvoi.

Abonnements#

Code	HTTP	Explication
`mandate_not_found`	404	Mandat inconnu ou n'appartenant pas au marchand.
`mandate_not_authorizable`	409	Le mandat n'est plus en attente d'autorisation.
`mandate_not_cancelable`	409	Mandat déjà annulé / terminé.
`mandate_not_pausable`	409	Le mandat n'est pas actif.
`mandate_not_resumable`	409	Le mandat n'est pas en pause.

Facturiers#

Code	HTTP	Explication
`no_biller`	404	Aucune fiche facturier liée à ce marchand.
`name_and_category_required`	400	Nom affiché ou catégorie manquant.
`reason_required`	400	Motif requis pour un rejet en back-office.
`no_pending_logo`	409	Aucun logo en attente de validation.
`file_required`	400	Aucun logo n'a été envoyé.
`invalid_type`	400	Logo non PNG/JPEG.
`invalid_size`	400	Logo vide ou > 512 Ko.
`too_small`	400	Logo < 128×128 px.
`slug_taken`	409	Slug de facturier ou de produit déjà utilisé.
`store_unavailable`	503	Stockage objet indisponible.
`store_failed`	502	Échec d'écriture dans le stockage objet.
`product_not_found`	404	Produit facturier introuvable.
`not_a_lookup_product`	400	Le produit visé n'utilise pas le mode `lookup`.
`lookup_unavailable`	502	Le backend du facturier n'a pas répondu correctement.
`quote_not_found`	404	Quote introuvable.
`quote_used`	409	Quote déjà consommé.
`quote_expired`	409	Quote expiré.
`biller_not_found`	404	Facturier introuvable dans l'annuaire.
`biller_not_payable`	409	Facturier ou produit non payable dans l'état courant.

Versements#

Code	HTTP	Explication
`insufficient_balance`	—	Solde de reversement insuffisant (au niveau de la ligne, `state=failed`).
`recipient_not_found`	—	Le `@tag` bénéficiaire n'existe pas (ligne `failed`).
`recipient_wallet_missing`	—	Le bénéficiaire n'a pas de portefeuille dans cette devise.
`payout_failed`	—	Échec du versement (raison générique).
`schedule_not_found`	404	Versement programmé inconnu.
`schedule_not_cancelable`	409	Déjà annulé / terminé.

Versements en masse

Dans un lot, chaque ligne réussit ou échoue indépendamment : un versement porte son propre state (paid/failed) et son failure_code. Le lot lui-même renvoie toujours 201 avec le détail par ligne.

Paiement (fallback web / app)#

Code	HTTP	Explication
`tag_not_found`	404	Identifiant `@tag` introuvable.
`invalid_otp`	401	Code SMS incorrect ou expiré.
`invalid_pin`	401	Code PIN incorrect.
`pin_locked`	429	Trop de tentatives — compte temporairement verrouillé.
`otp_unavailable`	429	Envoi d'OTP indisponible (anti-spam).
`challenge_required`	403	Vérification supplémentaire requise (anti-fraude).
`tx_blocked`	403	Paiement bloqué pour raison de sécurité.
`edd_required`	403	Vérification renforcée du compte requise.
`kyc_cap_exceeded`	403	Plafond du niveau de vérification atteint.
`payment_failed`	422	Paiement impossible (solde, etc.).

Serveur#

Code	HTTP	Explication
`internal`	500	Erreur interne — réessayez ; si ça persiste, contactez le support.