Une taxonomie des erreurs pour applications métier vous aide à classer les erreurs de validation, d'authentification, de limitations de débit et de dépendances afin que les alertes et les réponses UI restent cohérentes.
Une taxonomie d'erreurs est une façon partagée de nommer et de regrouper les erreurs pour que tout le monde les traite de la même manière. Plutôt que chaque écran et chaque API inventent leurs propres messages, vous définissez un petit ensemble de catégories (comme validation ou auth) et des règles sur la façon dont elles s'affichent pour les utilisateurs et dans la supervision.
Sans cette structure partagée, le même problème apparaît sous des formes différentes. Un champ requis manquant peut s'afficher comme « Bad Request » sur mobile, « Quelque chose s'est mal passé » sur le web, et un trace de pile dans les logs. Les utilisateurs ne savent pas quoi faire ensuite, et les équipes d'astreinte perdent du temps à deviner s'il s'agit d'une erreur utilisateur, d'une attaque ou d'une panne.
L'objectif est la cohérence : le même type d'erreur doit conduire au même comportement UI et au même comportement d'alerte. Les problèmes de validation doivent pointer le champ exact. Les problèmes d'autorisation doivent arrêter l'action et expliquer l'accès manquant. Les défaillances de dépendance doivent proposer une réessai sûr, tandis que la supervision déclenche la bonne alarme.
Un exemple réaliste : un commercial essaie de créer une fiche client, mais le service de paiement est en panne. Si votre application renvoie un 500 générique, il va réessayer et risquer de créer des doublons plus tard. Avec une catégorie claire de défaillance de dépendance, l'UI peut indiquer que le service est temporairement indisponible, empêcher les soumissions en double, et la supervision peut alerter la bonne équipe.
Ce type d'alignement compte surtout quand un backend alimente plusieurs clients. Si l'API, l'application web, le mobile et les outils internes s'appuient tous sur les mêmes catégories et codes, les pannes cessent d'avoir l'air aléatoires.
Les taxonomies restent plus faciles à maintenir quand vous séparez quatre choses qui se mélangent souvent : la catégorie (quel type de problème), le code (un identifiant stable), le message (texte humain) et les détails (contexte structuré). Le statut HTTP reste important, mais il ne doit pas raconter toute l'histoire.
La catégorie répond à : « Comment l'UI et la supervision doivent-elles se comporter ? » Un 403 peut signifier « auth » à un endroit, alors qu'un autre 403 pourrait être « policy » si vous ajoutez ensuite des règles. La catégorie concerne le comportement, pas le transport.
Le code répond à : « Que s'est-il exactement passé ? » Les codes doivent être stables et monotones. Si vous renommez un bouton ou refactorez un service, le code ne doit pas changer. Les dashboards, alertes et scripts de support dépendent de ça.
Le message répond à : « Que dire à une personne ? » Décidez pour qui le message est destiné. Un message utilisateur doit être court et bienveillant. Un message support peut inclure des étapes suivantes. Les logs peuvent être plus techniques.
Les détails répondent à : « De quoi avons-nous besoin pour réparer ? » Gardez les détails structurés pour que l'UI puisse réagir. Pour une erreur de formulaire, cela peut être les noms de champs. Pour un problème de dépendance, cela peut être le nom du service en amont et une valeur retry-after.
Voici une forme compacte que beaucoup d'équipes utilisent :
{
\"category\": \"validation\",\n \"code\": \"CUSTOMER_EMAIL_INVALID\",\n \"message\": \"Enter a valid email address.\",\n \"details\": { \"field\": \"email\", \"rule\": \"email\" }
}
À mesure que les fonctionnalités changent, gardez les catégories petites et stables, et ajoutez de nouveaux codes au lieu de réutiliser les anciens. Cela maintient le comportement UI, les tendances de supervision et les playbooks de support fiables au fil de l'évolution du produit.
La plupart des applications métier peuvent commencer avec quatre catégories qui apparaissent partout. Si vous les nommez et les traitez de la même façon dans le backend, le web et le mobile, votre UI pourra répondre de manière cohérente et votre supervision deviendra lisible.
Les erreurs de validation surviennent quand une saisie utilisateur ou une règle métier échoue. Ce sont des cas normaux et ils doivent être faciles à corriger : champs requis manquants, formats invalides, ou règles comme « la remise ne peut pas dépasser 20 % » ou « le total de la commande doit être > $0 ». L'UI doit surligner le champ ou la règle exacte, pas afficher une alerte générique.
Les erreurs d'auth se divisent généralement en deux cas : non authentifié (pas connecté, session expirée, token manquant) et non autorisé (connecté mais sans permission). Traitez-les différemment. « Veuillez vous reconnecter » convient au premier cas. Pour le second, évitez de révéler des détails sensibles, mais soyez clair : « Vous n'avez pas l'accès pour approuver les factures. »
La limitation de débit signifie « trop de requêtes, réessayez plus tard ». Elle apparaît souvent lors d'importations, de tableaux de bord chargés ou de retries répétés. Incluez un hint retry-after (même si c'est juste « attendez 30 secondes »), et faites en sorte que l'UI baisse la cadence au lieu de marteler le serveur.
Les défaillances de dépendances proviennent de services en amont, timeouts ou pannes : fournisseurs de paiement, envoi d'email/SMS, bases de données ou services internes. Les utilisateurs ne peuvent pas corriger ça, donc l'UI doit proposer un repli sûr (sauvegarder un brouillon, réessayer plus tard, contacter le support).
La différence clé est le comportement : les erreurs attendues font partie du flux normal et méritent un retour précis ; les erreurs inattendues signalent une instabilité et doivent déclencher des alertes, des correlation IDs et un journal soigneux.
Une taxonomie doit être assez petite pour être mémorisée, mais assez stricte pour que deux équipes étiquettent le même problème de la même façon.
Commencez par un atelier de 60 à 90 minutes. Listez les erreurs les plus fréquentes (mauvaise saisie, problèmes de connexion, trop de requêtes, pannes de tiers, bugs inattendus), puis regroupez-les en 6 à 12 catégories que tout le monde peut énoncer sans consulter un doc.
Choisissez un motif de nommage lisible dans les logs et tickets. Gardez-le court, évitez les numéros de version et considérez les codes comme permanents une fois publiés. Un modèle courant est un préfixe de catégorie plus un slug clair, comme AUTH_INVALID_TOKEN ou DEP_PAYMENT_TIMEOUT.
Avant de quitter la salle, décidez ce que chaque erreur doit inclure : catégorie, code, message sûr, détails structurés et trace ou request ID.
Les équipes bloquent quand les catégories deviennent une poubelle. Une règle simple aide : la catégorie répond à « Comment l'UI et la supervision réagissent ? », le code répond à « Que s'est-il passé exactement ? ». Si deux échecs nécessitent des comportements UI différents, ils ne devraient pas partager une catégorie.
Décidez ce que voient les utilisateurs par défaut. La validation surligne les champs. L'auth envoie à la connexion ou affiche un message d'accès. Les limites de débit affichent « réessayez dans X secondes ». Les défaillances de dépendance affichent un écran de réessai calme. Une fois ces comportements par défaut définis, les nouvelles fonctionnalités peuvent les suivre au lieu d'inventer un traitement ponctuel.
Exécutez cinq flux courants (inscription, paiement, recherche, édition admin, upload de fichier) et étiquetez chaque échec. Si le groupe discute, il vous faut généralement une règle plus claire, pas vingt codes supplémentaires.
La validation est le type d'échec que vous voulez généralement afficher immédiatement. Elle doit être prévisible : dire à l'utilisateur quoi corriger, et ne jamais déclencher une boucle de retry.
Les erreurs champ par champ et les erreurs de formulaire sont des problèmes différents. Les erreurs champ par champ concernent une seule saisie (email, téléphone, montant). Les erreurs de formulaire concernent la combinaison d'entrées (la date de début doit être avant la date de fin) ou des prérequis manquants (aucun mode de livraison sélectionné). Votre réponse API doit rendre cette différence claire pour que l'UI réagisse correctement.
Une règle métier fréquente est « plafond de crédit dépassé ». L'utilisateur a peut-être saisi un nombre valide, mais l'action n'est pas autorisée selon l'état du compte. Traitez cela comme une erreur de validation au niveau formulaire avec une raison claire et un indice sûr, par exemple : « Votre plafond disponible est de $500. Réduisez le montant ou demandez une augmentation. » Évitez d'exposer des noms internes comme noms de champs de base de données, modèles de scoring ou étapes du moteur de règles.
Une réponse actionnable inclut généralement un code stable (pas seulement une phrase en anglais), un message convivial, des pointeurs de champ optionnels pour les problèmes champ par champ, et de petits conseils sûrs (exemples de format, plages autorisées). Si vous avez besoin d'un nom de règle pour les ingénieurs, mettez-le dans les logs, pas dans l'UI.
Logguez les échecs de validation différemment des erreurs système. Vous voulez assez de contexte pour déboguer des tendances sans stocker de données sensibles. Enregistrez l'ID utilisateur, l'ID de requête, le nom ou code de la règle et quels champs ont échoué. Pour les valeurs, logguez seulement ce qu'il faut (souvent « présent/manquant » ou longueur) et masquez tout ce qui est sensible.
Dans l'UI, concentrez-vous sur la correction, pas le retry. Surlignez les champs, conservez ce que l'utilisateur a tapé, scrollez vers la première erreur et désactivez les retries automatiques. Les erreurs de validation ne sont pas temporaires, donc « réessayez » fait perdre du temps.
Les échecs d'authentification et d'autorisation se ressemblent pour les utilisateurs, mais ils impliquent des choses différentes pour la sécurité, le flux UI et la supervision. Les séparer rend le comportement cohérent sur web, mobile et clients API.
Non authentifié signifie que l'app ne peut pas prouver qui est l'utilisateur. Causes typiques : identifiants manquants, token invalide ou session expirée. Forbidden signifie que l'utilisateur est connu mais n'a pas le droit d'effectuer l'action.
La session expirée est le cas le plus courant. Si vous supportez des refresh tokens, tentez un refresh silencieux une fois, puis réessayez la requête d'origine. Si le refresh échoue, renvoyez une erreur non authentifiée et redirigez l'utilisateur vers la connexion. Évitez les boucles : après une tentative de refresh, arrêtez et exposez une étape suivante claire.
Le comportement UI doit rester prévisible :
Pour l'audit, logguez suffisamment pour répondre à « qui a tenté quoi et pourquoi cela a été bloqué » sans exposer de secrets. Un enregistrement utile inclut l'ID utilisateur (si connu), le tenant ou workspace, le nom de l'action, l'identifiant de la ressource, le timestamp, l'ID de requête et le résultat du contrôle de politique (allowed/denied). Gardez les tokens bruts et mots de passe hors des logs.
Dans les messages destinés aux utilisateurs, ne révélez pas les noms de rôles, règles de permission ou la structure interne des politiques. « Vous n'avez pas accès pour approuver les factures » est plus sûr que « Seul FinanceAdmin peut approuver les factures. »
Les limites de débit ne sont pas des bugs. Ce sont des rails de sécurité. Traitez-les comme une catégorie à part entière pour que l'UI, les logs et les alertes réagissent de façon cohérente quand le trafic augmente.
Les limites de débit apparaissent généralement sous quelques formes : par utilisateur (une personne qui clique trop vite), par IP (beaucoup d'utilisateurs derrière un réseau d'entreprise) ou par clé API (une intégration unique qui tourne à vide). La cause compte parce que la correction est différente.
Les clients ont besoin de deux choses : savoir qu'ils sont limités et quand réessayer. Retournez un HTTP 429 plus un temps d'attente clair (par exemple Retry-After: 30). Incluez aussi un code d'erreur stable (comme RATE_LIMITED) pour que les dashboards puissent grouper les événements.
Gardez le message calme et spécifique. « Trop de requêtes » est vrai mais peu utile. « Veuillez attendre 30 secondes puis réessayer » fixe des attentes et réduit les clics répétés.
Côté UI, empêchez les retries rapides. Un motif simple : désactiver l'action pendant la durée d'attente, afficher un court compte à rebours, puis proposer une tentative sûre quand le timer est terminé. Évitez les formulations qui font penser que les données ont été perdues.
La supervision est souvent l'endroit où les équipes sur-réagissent. Ne pagez pas quelqu'un pour chaque 429. Suivez les taux et alertez sur des pics inhabituels : une montée soudaine pour un endpoint, un tenant ou une clé API est actionnable.
Le backend doit aussi être prévisible. Utilisez un backoff exponentiel pour les retries automatiques et rendez les retries idempotents. Une action « Créer facture » ne doit pas créer deux factures si la première requête a réellement réussi.
Les défaillances de dépendances sont celles que les utilisateurs ne peuvent pas corriger par une meilleure saisie. L'utilisateur a fait tout correctement, mais le gateway de paiement a time-out, la connexion à la base de données a sauté, ou un service en amont a renvoyé un 5xx. Traitez-les comme une catégorie séparée pour que l'UI et la supervision se comportent de manière prédictible.
Commencez par nommer les formes communes d'échec : timeout, erreur de connexion (DNS, TLS, connexion refusée) et 5xx amont (bad gateway, service unavailable). Même si vous ne pouvez pas connaître la cause racine, vous pouvez capturer ce qui s'est passé et répondre de manière cohérente.
Les retries aident pour les courts incidents, mais ils peuvent aussi aggraver une panne. Utilisez des règles simples pour que chaque équipe prenne la même décision.
Quand une dépendance échoue, dites ce que l'utilisateur peut faire ensuite sans le blâmer : « Problème temporaire. Veuillez réessayer. » S'il existe un repli sûr, proposez-le. Exemple : si Stripe est en panne, laissez l'utilisateur sauvegarder la commande en « Paiement en attente » et envoyez une confirmation par email au lieu de perdre le panier.
Protégez aussi les utilisateurs contre les doubles soumissions. Si l'utilisateur appuie deux fois sur « Payer » pendant une réponse lente, votre système doit le détecter. Utilisez des clés d'idempotence pour les flux créer-et-prélever, ou des vérifications d'état comme « commande déjà payée » avant de relancer l'action.
Pour la supervision, logguez des champs qui répondent vite à une question : « Quelle dépendance échoue, et à quel point ? » Capturez le nom de la dépendance, l'endpoint ou l'opération, la durée et le résultat final (timeout, connect, upstream 5xx). Cela rend les alertes et dashboards utiles au lieu d'être bruyants.
Les taxonomies ne fonctionnent que quand chaque canal parle la même langue : l'API, l'UI web, le mobile et vos logs. Sinon, le même problème apparaît sous cinq messages différents et personne ne sait s'il s'agit d'une erreur utilisateur ou d'une vraie panne.
Traitez les codes HTTP comme une couche secondaire. Ils aident avec les proxies et le comportement client basique, mais votre catégorie et votre code doivent porter le sens. Un timeout de dépendance peut rester un 503, mais la catégorie dit à l'UI de proposer « Réessayer » et dit à la supervision de contacter l'astreinte.
Faites en sorte que chaque API retourne une forme d'erreur standard, même quand la source diffère (base de données, module auth, API tierce). Une forme simple comme celle-ci garde la gestion UI et les dashboards cohérents :
{
\"category\": \"dependency\",\n \"code\": \"PAYMENTS_TIMEOUT\",\n \"message\": \"Payment service is not responding.\",\n \"details\": {\"provider\": \"stripe\"},\n \"correlation_id\": \"9f2c2c3a-6a2b-4a0a-9e9d-0b0c0c8b2b10\"\n}
Les correlation IDs sont le pont entre « un utilisateur a vu une erreur » et « nous pouvons la tracer ». Affichez le correlation_id dans l'UI (un bouton de copie aide), et loggez-le toujours côté backend pour suivre une requête à travers les services.
Mettez-vous d'accord sur ce qu'il est sûr d'afficher dans l'UI vs ce qui doit rester dans les logs. Une séparation pratique : l'UI reçoit la catégorie, un message clair et une prochaine étape ; les logs reçoivent des détails techniques et le contexte de la requête ; les deux partagent correlation_id et code d'erreur stable.
La cohérence est ennuyeuse mais utile : chaque canal se comporte de la même façon, et la supervision dit la vérité.
Vérifiez d'abord le backend, y compris les jobs en arrière-plan et les webhooks. Si un champ est optionnel, les gens vont l'ignorer et la cohérence va se briser.
Ensuite, vérifiez les règles UI. Chaque catégorie doit correspondre à un comportement d'écran prévisible pour que les utilisateurs ne se demandent pas quoi faire ensuite : la validation surligne des champs, l'auth invite à se connecter ou affiche un accès, les limites de débit affichent une attente calme, les défaillances de dépendance proposent un retry et un repli lorsque possible.
Un test simple : déclenchez une erreur de chaque catégorie en staging et vérifiez que vous avez le même résultat dans l'application web, l'application mobile et le panneau admin.
La façon la plus rapide de casser un système d'erreurs est de le traiter comme une réflexion de dernière minute. Différentes équipes finissent par utiliser différents mots, différents codes et différents comportements UI pour le même problème. Le travail sur la taxonomie paie quand il reste cohérent.
Schémas d'échec fréquents :
Un exemple simple : un commercial soumet un formulaire « Créer un client » et reçoit un 403. Si l'UI traite tous les 4xx comme de la validation, il surlignera des champs au hasard et demandera de « corriger les saisies » au lieu de lui dire qu'il lui faut des droits. La supervision montrera alors un pic de « problèmes de validation » alors que le vrai problème est les rôles.
Prochaines étapes pratiques réalisables dans un court atelier : rédigez un doc d'une page (catégories, quand les utiliser, 5 à 10 codes canoniques), définissez les règles de message (ce que voient les utilisateurs vs ce qui va dans les logs), ajoutez une gate légère de revue pour les nouveaux codes, définissez les règles de retry par catégorie, puis implémentez de bout en bout (réponse backend, mapping UI et dashboards de supervision).
Si vous construisez avec AppMaster (appmaster.io), cela aide à centraliser ces règles en un seul endroit pour que la même catégorie et le même comportement de code s'appliquent au backend, à l'app web et aux apps mobiles natives.
Quand vaut-il la peine de créer une taxonomie d'erreurs ?Commencez lorsque le même backend sert plus d'un client (web, mobile, outils internes), ou lorsque le support et l'équipe d'astreinte demandent sans cesse : « Est-ce une erreur utilisateur ou un problème système ? » Une taxonomie rapporte vite ses bénéfices dès que vous avez des flux répétés comme l'inscription, le paiement, les importations ou les modifications administratives où un traitement cohérent compte.
Combien de catégories d'erreurs devons-nous commencer avec ?Un bon point de départ : 6 à 12 catégories que les gens peuvent retenir sans consulter la doc. Gardez-les stables et larges (par exemple validation, auth, rate_limit, dependency, conflict, internal) et exprimez la situation spécifique avec un code, pas une nouvelle catégorie.
Quelle est la différence entre une catégorie d'erreur et un code d'erreur ?La catégorie guide le comportement, le code identifie la situation exacte. La catégorie dit à l'UI et à la supervision quoi faire (surligner des champs, demander une authentification, faire une pause, proposer une réessai), tandis que le code reste stable pour les tableaux de bord, alertes et scripts de support même si le texte de l'UI change.
Le message doit-il être identique au code d'erreur ?Considérez les messages comme du contenu, pas comme des identifiants. Retournez un court message sûr pour l'utilisateur dans l'UI, et comptez sur le code stable pour le regroupement et l'automatisation. Si vous avez besoin d'un texte plus technique, gardez-le dans les logs et liez-le au même correlation ID.
Que doit contenir chaque réponse d'erreur d'API ?Incluez une catégorie, un code stable, un message sûr pour l'utilisateur, des détails structurés et un correlation ID ou request ID. Les détails doivent être utilisables par le client (quel champ a échoué, combien de secondes attendre) sans vider le texte brut d'exception.
Comment rendre les erreurs de validation exploitables au lieu d'être génériques ?Retournez des pointeurs au niveau champ quand c'est possible, pour que l'UI surligne l'entrée exacte et conserve ce que l'utilisateur a saisi. Utilisez une erreur au niveau formulaire quand le problème concerne une combinaison de champs ou une règle métier (plages de dates, limites de crédit) pour éviter que l'UI n'essaie de deviner le mauvais champ.
Comment gérer les erreurs « non connecté » vs « pas d'autorisation » ?Une erreur non authentifiée signifie que l'utilisateur n'est pas connecté ou que la session/token est invalide : l'UI doit l'envoyer se connecter et préserver sa tâche. Forbidden signifie qu'il est connecté mais sans permission : l'UI doit rester sur la page et afficher un message d'accès sans révéler les rôles ou règles internes.
Quelle est la bonne manière d'implémenter les erreurs de limite de débit ?Retournez un temps d'attente explicite (par exemple une valeur retry-after) et conservez un code stable pour que les clients appliquent un backoff cohérent. Dans l'UI, empêchez les clics répétés et montrez une étape suivante claire : des retries automatiques rapides aggravent souvent la limitation.
Quand devons-nous réessayer les défaillances de dépendances, et comment éviter les doublons ?Retry uniquement quand l'échec est probablement temporaire (timeouts, reset de connexion, 502/503 en amont) et plafonnez les tentatives avec un petit backoff. Pour les actions non-idempotentes, exigez une clé d'idempotence ou une vérification d'état, sinon un retry peut créer des doublons si la première tentative a réussi.
Comment les correlation IDs aident-ils lors d'incidents réels, et où doivent-ils apparaître ?Affichez le correlation ID à l'utilisateur (pour que le support puisse le demander) et loggez-le toujours côté serveur avec le code et les détails clés. Cela permet de tracer une erreur à travers services et clients ; dans les projets AppMaster, centraliser cette forme aide à aligner backend, web et mobile natif.
21 janv. 2026
8 min
20 janv. 20268 min
20 janv. 20268 minExpérimentez avec AppMaster avec un plan gratuit.
Lorsque vous serez prêt, vous pourrez choisir l'abonnement approprié.
