Gestion des erreurs

Structure des erreurs

{
  "statusCode": 400,
  "message": "Le montant doit être supérieur à 100 XOF",
  "error": "Bad Request"
}

Codes HTTP

Code	Signification	Action
`200`	Succès	-
`400`	Requête invalide	Vérifier les paramètres
`401`	Non authentifié	Vérifier la clé API
`403`	Accès refusé	Vérifier les permissions
`404`	Ressource non trouvée	Vérifier l’identifiant
`422`	Erreur métier	Voir le code d’erreur
`429`	Trop de requêtes	Attendre et réessayer
`500`	Erreur serveur	Contacter le support

Erreurs de validation

Champ	Règle	Message
`amount`	Min: 100, Max: 5000000	”Le montant doit être entre 100 et 5 000 000”
`currency`	XOF, XAF, EUR, USD	”Devise non supportée”
`customerPhone`	Format E.164	”Format de numéro invalide”
`provider`	Valeur valide	”Méthode de paiement invalide”

Erreurs de paiement

Code	Description	Action
`insufficient_funds`	Solde client insuffisant	Informer le client
`user_cancelled`	Annulé par le client	Proposer de réessayer
`timeout`	Délai expiré	Réinitier le paiement
`provider_error`	Erreur du provider	Réessayer plus tard
`invalid_phone`	Numéro invalide	Vérifier le format E.164

Erreurs de payout

Code	Description	Action
`invalid_recipient`	Bénéficiaire invalide	Vérifier le numéro/compte
`insufficient_balance`	Votre solde insuffisant	Recharger votre compte
`provider_error`	Erreur du provider	Réessayer plus tard
`limit_exceeded`	Limite dépassée	Vérifier les limites de la devise concernée
`account_blocked`	Compte bloqué	Contacter le support

`INSUFFICIENT_BALANCE` au devis

POST /payouts/quote renvoie un 400 structuré, qui nomme les devises que vous pouvez autoriser à la conversion plutôt que de vous laisser deviner :

{
  "code": "INSUFFICIENT_BALANCE",
  "message": "Solde insuffisant. XOF: 130 disponible pour 632 requis — Convertible depuis: 99180 CDF, relancez le devis avec allowFxFrom.",
  "balanceCategory": "collect",
  "attempts": [{ "currency": "XOF", "required": 632, "available": 130 }],
  "convertibleFrom": [{ "currency": "CDF", "available": 99180 }]
}

Reprenez une valeur de convertibleFrom dans le champ allowFxFrom du devis. Si la liste est vide, aucun de vos portefeuilles ne couvre le manque : il faut approvisionner le compte. Voir le guide Multi-devises.

Rate limiting

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705312800

En cas de 429 Too Many Requests, attendez le timestamp X-RateLimit-Reset avant de réessayer.

Erreurs d’intégration courantes

Se fier à la redirection au lieu du webhook

Le returnUrl ne garantit pas le succès. Attendez toujours le webhook payment.completed.

Clé secrète exposée côté client

N’utilisez jamais sk_* dans du JavaScript navigateur. La clé secrète reste côté serveur uniquement.

Mauvais format de numéro

Envoyez +221771234567 (E.164), pas 771234567 ou 00221771234567.

Mélange d'environnements

Les clés sk_test_* ne fonctionnent qu’avec sandbox-api.caurisflux.com. Les clés sk_live_* uniquement avec prod-api.caurisflux.com.

transaction_id non sauvegardé

Stockez toujours le transactionId retourné. Sans lui, impossible de lier le webhook à votre commande.

Démarrage

Intégration

Production

Structure des erreurs

Codes HTTP

Erreurs de validation

Erreurs de paiement

Erreurs de payout

`INSUFFICIENT_BALANCE` au devis

Rate limiting

Erreurs d’intégration courantes

​Structure des erreurs

​Codes HTTP

​Erreurs de validation

​Erreurs de paiement

​Erreurs de payout

​INSUFFICIENT_BALANCE au devis

​Rate limiting

​Erreurs d’intégration courantes

Structure des erreurs

Codes HTTP

Erreurs de validation

Erreurs de paiement

Erreurs de payout

`INSUFFICIENT_BALANCE` au devis

Rate limiting

Erreurs d’intégration courantes