Gestion des erreurs

Ce guide documente les erreurs retournées par l’API CaurisFlux et les stratégies de résolution.

​

Structure des erreurs

Toutes les erreurs suivent le même format :

​

Codes HTTP

​

Erreurs d’authentification

​

UNAUTHORIZED

Causes :

• Clé API manquante dans l’en-tête
• Clé API invalide ou révoquée
• Format incorrect (clé publique ou secrète manquante)

​

FORBIDDEN

Causes :

• Clé publique utilisée pour une action réservée à la clé secrète
• IP non autorisée (si liste blanche configurée)
• Compte suspendu

​

Erreurs de validation

​

VALIDATION_ERROR

Validations communes : Exemple de gestion :

​

Erreurs de paiement

​

Erreurs de limite

​

RATE_LIMIT_EXCEEDED

Limites par défaut :

• 100 requêtes par minute
• 1000 requêtes par heure

Gestion avec retry :

​

DAILY_LIMIT_EXCEEDED

​

Erreurs de remboursement

​

REFUND_NOT_ALLOWED

Causes :

• Transaction non réussie
• Délai de remboursement dépassé
• Déjà entièrement remboursé

​

INVALID_REFUND_AMOUNT

​

Gestion globale des erreurs

​

Messages d’erreur utilisateur

Traduisez les codes d’erreur en messages compréhensibles :

​

Logs et monitoring

​

Logger les erreurs

​

Alertes automatiques

Configurez des alertes pour les erreurs critiques :

• Taux d’erreur > 5%
• Erreurs PROVIDER_ERROR répétées
• Erreurs UNAUTHORIZED (possible compromission de clé)

​

Erreurs d’intégration courantes

​

1. Se fier uniquement à la redirection

Problème : Considérer un paiement comme réussi quand le client revient sur return_url. Solution : Toujours attendre le webhook payment.success avant de confirmer une commande.

​

2. Ne pas vérifier la signature webhook

Problème : Accepter les webhooks sans vérification. Risque : Un attaquant peut envoyer de faux webhooks pour simuler des paiements. Solution : Toujours vérifier la signature HMAC-SHA256.

​

3. Exposer la clé secrète côté client

Problème : Utiliser sk_* dans du code JavaScript côté navigateur. Risque : Compromission totale du compte. Solution : La clé secrète doit rester uniquement côté serveur.

​

4. Ignorer les statuts intermédiaires

Problème : Ne gérer que success et ignorer pending, processing. Solution : Implémenter une logique pour tous les statuts :

​

5. Ne pas stocker le transaction_id

Problème : Ne pas sauvegarder le transaction_id retourné par l’API. Conséquence : Impossible de lier le webhook à la commande, impossible de vérifier le statut. Solution : Toujours stocker le transaction_id dans votre base de données.

​

6. Timeout webhook trop long

Problème : Traitement webhook qui prend plus de 5 secondes. Conséquence : CaurisFlux considère le webhook comme échoué et retente. Solution : Répondre immédiatement et traiter en arrière-plan.

​

7. Mauvais format de numéro de téléphone

Problème : Envoyer 771234567 au lieu de +221771234567. Solution : Toujours utiliser le format E.164 international.

​

8. Mélanger les environnements

Problème : Utiliser des clés sk_test_* vers l’API de production. Solution : Vérifier que les clés correspondent à l’environnement :

​

Support

Si vous rencontrez des erreurs persistantes :

• Email : support@cauris-pay.com
• Status : status.cauris-pay.com

Incluez dans votre demande :

• Le code d’erreur
• Le transaction_id si applicable
• La date et l’heure
• Les paramètres de la requête (sans les données sensibles)