Gestion des Erreurs

AWDPay utilise des codes HTTP standards combinés à des codes d'erreur internes pour vous aider à diagnostiquer et résoudre rapidement les problèmes.

Format de réponse d'erreur

{
  "error": {
    "code": 40010,
    "message": "Montant invalide",
    "details": "Le montant doit être supérieur à 0"
  }
}

Champ	Type	Description
code	Integer	Code d'erreur AWDPay (voir tableau ci-dessous)
message	String	Message lisible décrivant l'erreur
details	String	Détails supplémentaires (optionnel)

---

Codes d'erreur par catégorie

🔐 Authentification & Autorisation

Code	Nom	HTTP	Description	Action Recommandée
401	InvalidRole	401	Rôle invalide ou insuffisant	Vérifiez vos permissions de compte
30001	KEYCLOAK_ERROR	500	Erreur du serveur d'authentification	Réessayez, contactez le support si persistant
40001	INVALID_ACCESS	403	Accès non autorisé à cette ressource	Vérifiez vos droits d'accès
40002	UNAUTHORIZE_REQUEST	401	Requête non autorisée	Vérifiez votre token Bearer

🔍 Ressources non trouvées

Code	Nom	HTTP	Description	Action Recommandée
40004	RESSOURCE_NOT_FOUND	404	Ressource non trouvée	Vérifiez l'identifiant de ressource
40005	PHONE_NUMBER_NOT_FOUND	404	Numéro de téléphone non trouvé	Vérifiez le format et l'existence du numéro
40006	TRX_NOT_FOUND	404	Transaction non trouvée	Vérifiez la référence de transaction
40007	OTP_NOT_FOUND	404	OTP non trouvé ou expiré	Demandez un nouvel OTP
40008	CUSTOMER_NOT_FOUND	404	Client non trouvé	Vérifiez les informations client
40017	WALLET_NOT_FOUND	404	Portefeuille non trouvé	Vérifiez que le compte existe

⚠️ Erreurs de validation

Code	Nom	HTTP	Description	Action Recommandée
40010	INVALID_AMOUNT	400	Montant invalide	Le montant doit être > 0
40011	INVALID_COUNTRY	400	Code pays invalide	Utilisez un code ISO 3166-1 alpha-2 valide
40012	INVALID_GATEWAY	400	Passerelle invalide	Vérifiez le nom de la passerelle
40014	INVALID_NUMBER	400	Numéro invalide	Utilisez le format international (+XXX...)
40015	INVALID_CURRENCY	400	Devise invalide	Utilisez un code ISO 4217 (XOF, EUR...)
40016	INVALID_JSON_BODY	400	Corps JSON invalide	Vérifiez la syntaxe JSON
40017	INVALID_METHOD	400	Méthode invalide	Utilisez une méthode HTTP supportée
40018	INVALID_CLIENT	400	Client invalide	Vérifiez vos identifiants API
40019	INVALID_OTP	400	Code OTP invalide	Vérifiez le code saisi
40020	INVALID_OPERATION	400	Opération invalide	Cette opération n'est pas autorisée
40021	INVALID_CALLBACK_URL	400	URL de callback invalide	Utilisez une URL HTTPS valide
40022	INVALID_SECRET_CODE	400	Code secret invalide	Vérifiez votre code secret
40023	INVALID_REQUEST	400	Requête invalide	Vérifiez les paramètres de requête

💰 Erreurs de solde

Code	Nom	HTTP	Description	Action Recommandée
40013	INSUFFICIENT_BALANCE	422	Solde insuffisant	Rechargez votre compte marchand

---

Codes HTTP standards

Code HTTP	Signification	Description
200	OK	Requête réussie
201	Created	Ressource créée avec succès
400	Bad Request	Paramètres invalides
401	Unauthorized	Token manquant ou invalide
403	Forbidden	Accès refusé
404	Not Found	Ressource non trouvée
422	Unprocessable Entity	Validation métier échouée
429	Too Many Requests	Limite de taux atteinte
500	Internal Server Error	Erreur serveur
502	Bad Gateway	Erreur de passerelle externe
503	Service Unavailable	Service temporairement indisponible

---

Gestion des erreurs par type

Erreurs 4xx (Client)

Ces erreurs sont causées par des données invalides. Ne réessayez pas sans corriger la requête.

async function handleClientError(response) {
  const error = await response.json();
  
  switch (error.code) {
    case 40010: // INVALID_AMOUNT
      throw new Error('Montant invalide : doit être supérieur à 0');
    
    case 40013: // INSUFFICIENT_BALANCE
      throw new Error('Solde insuffisant pour cette opération');
    
    case 40014: // INVALID_NUMBER
      throw new Error('Format de numéro invalide');
    
    default:
      throw new Error(error.message);
  }
}

Erreurs 5xx (Serveur)

Ces erreurs sont temporaires. Réessayez avec un backoff exponentiel.

async function retryWithBackoff(fn, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status >= 500 && attempt < maxRetries - 1) {
        const delay = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      throw error;
    }
  }
}

---

Idempotence et nouvel essai

Utilisation de l'en-tête Idempotency-Key

Pour éviter les doublons lors des nouvelles tentatives, utilisez une clé d'idempotence :

curl -X POST "https://app.awdpay.com/api/deposits/initiate" \
  -H "Authorization: Bearer $AWDPAY_TOKEN" \
  -H "Idempotency-Key: order-1234-attempt-1" \
  -H "Content-Type: application/json" \
  -d '{...}'

Stratégie de nouvel essai recommandée

Tentative	Délai	Action
1	Immédiat	Première tentative
2	1 seconde	Si erreur 5xx ou timeout
3	2 secondes	Si erreur 5xx ou timeout
4	4 secondes	Si erreur 5xx ou timeout
5+	Abandonner	Alerter l'équipe technique

Ne jamais réessayer

• Erreurs 4xx (sauf 429 Too Many Requests)
• Erreurs INSUFFICIENT_BALANCE
• Erreurs INVALID_*

---

Meilleures pratiques

✅ À faire

• Enregistrer toutes les erreurs avec code, message et horodatage
• Utiliser des clés d'idempotence pour les opérations de création
• Implémenter un disjoncteur pour les erreurs récurrentes
• Afficher des messages clairs aux utilisateurs (pas de codes techniques)

❌ À ne pas faire

• Exposer les codes internes aux utilisateurs finaux
• Réessayer aveuglément sans analyser l'erreur
• Ignorer les erreurs — enregistrez-les même si non-bloquantes

---

Support

Si vous rencontrez des erreurs persistantes :

1. Notez le code d'erreur, le message et l'horodatage
2. Récupérez la référence de transaction si disponible
3. Contactez le support via le tableau de bord AWDPay
4. Fournissez les journaux requête/réponse (sans données sensibles)