Code de cause stable
Un code d’erreur stable est utilisé dans la logique client, le reporting et le routage automatique des demandes.
Documentation / Erreurs API
Gestion des erreurs API
Un modèle unifié pour les réponses, codes d’erreur, défaillances temporaires, résultats inconnus, diagnostics et récupération sécurisée des intégrations iGaming.
HTTP
résultat de la requête
Codes
cause claire
Nouvelle tentative
action sûre
Traçage
diagnostic de la requête
Cycle de gestion des erreurs
De la réponse API à la récupération
01
Déterminer le type de résultat
Vérifier le statut HTTP, le code de cause, la catégorie d’erreur et l’état de l’opération.
02
Enregistrer les données pour l’analyse
Consigner les identifiants de requête et d’opération, le point de terminaison, l’heure, la référence fournisseur et les paramètres sûrs.
03
Choisir une action sûre
Corriger les données, arrêter l’opération, réessayer après un délai ou vérifier l’état actuel.
04
Récupérer et contrôler
Éviter les doublons, rapprocher les résultats, informer les équipes responsables et traiter la cause racine.
Vue d’ensemble
Une erreur doit expliquer la cause et l’action suivante
Une réponse HTTP 400 ou 500 ne suffit pas. Une API fiable renvoie un code de cause stable, associe la réponse à un identifiant de requête et permet de savoir s’il faut corriger les données, arrêter l’opération, relancer la requête ou vérifier séparément son état.
Action prévisible
La catégorie d’erreur indique si la requête peut être relancée et quelles données doivent être modifiées.
Corrélation pour le diagnostic
Les identifiants de requête, d’opération et de fournisseur relient les journaux clients aux systèmes internes et à l’assistance.
Structure des erreurs
Structure recommandée d’une réponse d’erreur
La réponse doit être compacte, stable et adaptée au traitement automatisé sans exposer l’implémentation interne ni les données sensibles.
Code d’erreur
Identifiant stable de la cause, qui ne change pas lorsque le message explicatif est modifié.
Description
Explication brève et sûre, sans code interne, requêtes de base de données, secrets ni détails inutiles.
ID de requête
Identifiant unique permettant de retrouver l’opération dans les journaux et de contacter l’assistance.
Données complémentaires
Statut autorisé, limite, état actuel ou motif de refus sûr.
Nouvelle tentative possible
Indication explicite d’une erreur temporaire, sans suppression de la protection contre les doublons de l’opération.
Délai avant nouvelle tentative
Délai recommandé en secondes ou en-tête HTTP utilisé pour la limitation du débit et les indisponibilités temporaires.
Erreurs de champs
Liste des champs problématiques avec code de cause, chemin de la valeur et explication sûre.
Référence à la documentation
Lien permanent ou identifiant de section décrivant la cause et la manière de la corriger.
Catégories d’erreurs
Principales catégories d’erreurs
Le statut HTTP indique la classe générale du résultat, tandis que le code interne précise la cause exacte et l’action autorisée.
Erreur de validation des données d’entrée
Format incorrect, champ obligatoire manquant, valeur non prise en charge, précision de montant incorrecte ou structure de requête invalide.
Erreur d’authentification
Jeton, clé API, signature, horodatage de requête ou nonce manquant, expiré ou invalide.
Autorisations insuffisantes
Le client est reconnu mais ne dispose pas du rôle, de la marque, du marché ou de l’autorisation requis pour l’action.
Objet introuvable
Un joueur, paiement, tour, contrôle KYC, fournisseur ou autre objet n’existe pas ou n’est pas accessible au client.
Conflit d’état
La version ou l’état de l’objet a changé, ou l’identifiant d’opération a déjà été utilisé avec d’autres paramètres.
Violation d’une règle métier
Solde insuffisant, limite dépassée, joueur bloqué, marché interdit ou transition d’état non valide.
Trop de requêtes
Le nombre de requêtes autorisé pour le client, la méthode, le rôle ou l’opération critique a été dépassé.
Fournisseur indisponible
Le service externe est indisponible, répond lentement ou n’accepte temporairement plus d’opérations.
Erreur interne
Erreur inattendue de la plateforme, sans exposition des détails internes, mais avec un identifiant permettant le diagnostic.
Nouvelles tentatives et récupération
Nouvelle tentative et résultat inconnu
Une nouvelle tentative n’est sûre qu’après avoir identifié le type d’erreur et vérifié si l’opération initiale a pu être exécutée.
01
Vérifier si une nouvelle tentative est autorisée
Les erreurs de données, d’autorisation et de règles métier exigent généralement de corriger la requête plutôt que de la renvoyer.
02
Conserver la même clé d’opération
Relancer une opération financière, de jeu ou autre opération critique ne doit pas créer un nouveau résultat.
03
Augmenter le délai entre les tentatives
Les intervalles augmentent progressivement, respectent le délai indiqué par le serveur et limitent le nombre total de tentatives.
04
Arrêter et transmettre pour examen
Une fois toutes les tentatives épuisées, l’opération est enregistrée comme incomplète et transmise pour examen manuel ou rapprochement.
L’absence de réponse ne signifie pas que l’opération a échoué
Si la connexion est interrompue après l’envoi d’une requête, le résultat peut rester inconnu. Avant de réessayer, vérifiez l’état à l’aide de l’identifiant d’opération ou attendez une notification fiable.
Diagnostic et contrôle
Journaux, identifiants, métriques et alertes
Le diagnostic doit permettre de reconstituer le chemin de la requête entre la plateforme, l’adaptateur et le fournisseur externe sans stocker de données sensibles inutiles.
Contexte d’analyse
Identifiants de requête, de corrélation, d’opération et du fournisseur externe.
Point de terminaison, méthode HTTP, environnement, client, heure et durée de réponse.
Statut HTTP, code d’erreur, nombre de tentatives et état final.
Champs sensibles masqués, en-têtes sûrs et résultat de validation de la signature.
Surveillance et alertes
Taux d’erreur par méthode, fournisseur, client et catégorie de cause.
Hausse des réponses lentes, des erreurs HTTP 5xx, des signatures invalides et des événements de limitation du débit.
Nombre de nouvelles tentatives, d’opérations au résultat inconnu et de tâches de récupération.
Alertes avec seuils, responsables et règles d’escalade.
Tests
Éléments à tester dans l’environnement de test
L’environnement de test doit reproduire chaque catégorie d’erreur importante et confirmer le comportement correct du client, des nouvelles tentatives et des contrôles.
Erreurs de validation des données d’entrée
Champs manquants, types invalides, valeurs non prises en charge, précision des montants et plusieurs erreurs simultanées.
Accès et autorisations
Clé invalide, jeton expiré, signature incorrecte, rôle non autorisé, IP bloquée et nonce réutilisé.
Absence de réponse et résultat inconnu
Rupture de connexion avant l’envoi, après l’acceptation de l’opération et pendant la réception de la réponse finale.
Limitation du débit
HTTP 429, délai recommandé, requêtes simultanées et reprise après expiration de la limite.
Erreurs du fournisseur
Indisponibilité, maintenance, réponse invalide, notification retardée et statut contradictoire.
Nouvelle tentative et arrêt de protection
Limitation du nombre de tentatives, augmentation des délais, arrêt temporaire des requêtes, récupération contrôlée et escalade manuelle.
Liste de contrôle avant lancement
Une intégration de production est lancée après validation de la structure des erreurs, du comportement du client, de la protection contre les doublons et du diagnostic.
Toutes les erreurs renvoient un code de cause stable et un identifiant de requête.
Les détails des erreurs n’exposent ni secrets ni implémentation interne.
Les catégories d’erreurs temporaires et permanentes sont documentées.
Une opération critique relancée utilise la même clé d’idempotence.
Un résultat inconnu est traité en vérifiant l’état ou en recevant une notification fiable.
Les journaux, métriques, alertes, une file de récupération et les règles d’escalade sont configurés.
Besoin de standardiser les erreurs API ?
Envoyez-nous vos réponses HTTP actuelles, codes d’erreur, règles de nouvelle tentative et scénarios problématiques. APIACE vous aidera à définir un modèle d’erreur unifié, une récupération sûre et une approche de contrôle.