Patterns de gestion des erreurs d'API Go pour des réponses claires et cohérentes

Pourquoi des erreurs d'API incohérentes frustrent les clients

Quand chaque endpoint rapporte les échecs différemment, les clients cessent de faire confiance à votre API. Une route renvoie { "error": "not found" }, une autre renvoie { "message": "missing" }, et une troisième envoie du texte brut. Même si le sens est proche, le code client doit maintenant deviner ce qui s'est passé.

Le coût apparaît rapidement. Les équipes écrivent une logique d'analyse fragile et ajoutent des cas spéciaux par endpoint. Les réessais deviennent risqués car le client ne peut pas distinguer « réessayer plus tard » de « votre saisie est incorrecte ». Les tickets de support augmentent parce que le client voit un message vague, et votre équipe ne peut pas facilement le rattacher à une ligne de logs côté serveur.

Un scénario courant : une application mobile appelle trois endpoints pendant l'inscription. Le premier renvoie HTTP 400 avec une carte d'erreurs au niveau des champs, le deuxième renvoie HTTP 500 avec une trace de pile sous forme de chaîne, et le troisième renvoie HTTP 200 avec { "ok": false }. L'équipe de l'app publie trois handlers d'erreur différents, et votre équipe backend reçoit toujours des rapports du type « l'inscription échoue parfois » sans indice clair par où commencer.

L'objectif est un seul contrat prévisible. Les clients doivent pouvoir lire de façon fiable ce qui s'est passé : si c'est de leur faute ou la vôtre, si un réessai est pertinent, et un identifiant de requête qu'ils peuvent coller dans le support.

Note sur le périmètre : ceci se concentre sur les API HTTP JSON (pas gRPC), mais les mêmes idées s'appliquent partout où vous renvoyez des erreurs à d'autres systèmes.

Un objectif simple : un seul contrat suivi par tous les endpoints

Choisissez un contrat clair pour les erreurs et faites en sorte que chaque endpoint le respecte. « Cohérent » signifie la même forme JSON, la même signification des champs et le même comportement quel que soit le handler qui échoue. Une fois fait, les clients arrêtent de deviner et commencent à gérer les erreurs.

Un contrat utile aide les clients à décider quoi faire ensuite. Pour la plupart des applications, chaque réponse d'erreur doit répondre à trois questions :

• Puis-je corriger ma saisie ?
• Dois-je réessayer plus tard ?
• Dois-je contacter le support ?

Un ensemble de règles pratiques :

• Un seul schéma de réponse pour toutes les erreurs.
• Une seule politique de code de statut (le même type d'erreur correspond toujours au même statut HTTP).
• Une seule politique de message sûr (ce que les utilisateurs peuvent voir vs ce qui reste interne).
• Un seul crochet de corrélation (un request ID renvoyé pour que le support retrouve l'échec).

Décidez à l'avance ce qui ne doit jamais apparaître dans les réponses. Les éléments courants à bannir incluent fragments SQL, traces de pile, noms d'hôtes internes, secrets et chaînes d'erreur brutes provenant de dépendances.

Gardez une séparation propre : un message court destiné à l'utilisateur (sûr, poli, actionnable) et des détails internes (erreur complète, pile et contexte) conservés dans les logs. Par exemple, « Impossible d'enregistrer vos modifications. Veuillez réessayer. » est sûr. « pq: duplicate key value violates unique constraint users_email_key » ne l'est pas.

Quand tous les endpoints suivent le même contrat, les clients peuvent bâtir un seul gestionnaire d'erreurs réutilisable partout.

Définir un schéma de réponse d'erreur sur lequel les clients peuvent compter

Les clients ne peuvent gérer proprement les erreurs que si chaque endpoint répond avec la même forme. Choisissez une enveloppe JSON et maintenez-la stable.

Un défaut pratique est un objet error plus un request_id au niveau supérieur :

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Some fields are invalid.",
    "details": {
      "fields": {
        "email": "must be a valid email address"
      }
    }
  },
  "request_id": "req_01HV..."
}

Le statut HTTP donne la catégorie large (400, 401, 409, 500). Le error.code lisible par machine donne le cas spécifique sur lequel le client peut faire un branchement. Cette séparation compte parce que beaucoup de problèmes différents partagent le même statut. Une app mobile peut afficher des UI différentes pour EMAIL_TAKEN vs WEAK_PASSWORD, même si les deux renvoient 400.

Conservez error.message sûr et destiné à un humain. Il doit aider l'utilisateur à corriger le problème, mais ne jamais divulguer d'internes (SQL, traces, noms de fournisseurs, chemins de fichiers).

Les champs optionnels sont utiles lorsqu'ils restent prévisibles :

• Erreurs de validation : details.fields comme une map champ → message.
• Limites de débit ou problèmes temporaires : details.retry_after_seconds.
• Indications supplémentaires : details.docs_hint en texte brut (pas une URL).

Pour la compatibilité ascendante, traitez les valeurs de error.code comme faisant partie de votre contrat d'API. Ajoutez de nouveaux codes sans changer les anciens. N'ajoutez que des champs optionnels et supposez que les clients ignorent les champs inconnus.

Erreurs typées en Go : un modèle propre pour vos handlers

La gestion des erreurs devient chaotique quand chaque handler invente sa propre manière de signaler un échec. Un petit ensemble d'erreurs typées règle cela : les handlers retournent des types d'erreur connus, et une couche de réponse transforme ces erreurs en réponses cohérentes.

Un ensemble de départ pratique couvre la plupart des endpoints :

• ValidationError (mauvaise saisie)
• NotFoundError (ressource manquante)
• ConflictError (contrainte unique, incompatibilité d'état)
• UnauthorizedError (non authentifié ou pas autorisé)
• InternalError (tout le reste)

L'important est la stabilité au niveau supérieur, même si la cause racine change. Vous pouvez envelopper des erreurs de bas niveau (SQL, réseau, parsing JSON) tout en retournant le même type public que le middleware peut détecter.

type NotFoundError struct {
	Resource string
	ID       string
	Err      error // private cause
}

func (e NotFoundError) Error() string { return "not found" }
func (e NotFoundError) Unwrap() error { return e.Err }

Dans votre handler, retournez NotFoundError{Resource: "user", ID: id, Err: err} au lieu de divulguer sql.ErrNoRows directement.

Pour vérifier les erreurs, préférez errors.As pour les types personnalisés et errors.Is pour les erreurs sentinelles. Les erreurs sentinelles (comme var ErrUnauthorized = errors.New("unauthorized")) conviennent aux cas simples, mais les types personnalisés l'emportent quand vous avez besoin d'un contexte sûr (comme quelle ressource manquait) sans changer votre contrat public de réponse.

Soyez strict sur ce que vous attachez :

• Public (sûr pour les clients) : un message court, un code stable, et parfois un nom de champ pour la validation.
• Privé (logs seulement) : Err sous-jacente, info de pile, erreurs SQL brutes, tokens, données utilisateur.

Cette séparation vous permet d'aider les clients sans exposer les internals.

Mapper les types d'erreur vers des statuts HTTP de façon cohérente

Une fois que vous avez des erreurs typées, l'étape suivante est ennuyeuse mais essentielle : le même type d'erreur doit toujours produire le même statut HTTP. Les clients construiront de la logique autour de cela.

Un mapping pratique qui fonctionne pour la plupart des API :

Deux distinctions qui évitent beaucoup de confusion :

• 400 vs 422 : utilisez 400 quand vous ne pouvez pas interpréter la requête de façon fiable (JSON invalide, types erronés). Utilisez 422 quand vous pouvez la parser, mais que les valeurs ne conviennent pas.
• 409 vs 422 : utilisez 422 pour la validation au niveau des champs (mot de passe trop court). Utilisez 409 quand les données sont valides mais ne peuvent être appliquées à cause d'un état (email déjà pris, commande déjà expédiée, échec d'optimistic lock).

Des indications sur les réessais :

• Généralement sûr de réessayer : 503, et parfois 429 (après attente).
• Généralement pas sûr de réessayer sans changements : 400, 401, 403, 404, 409, 422.
• Si l'opération est idempotente (PUT avec le même corps, ou POST avec une clé d'idempotence), les réessais deviennent plus sûrs même après des échecs transitoires.

Request IDs : le moyen le plus rapide pour déboguer les problèmes clients

Un request ID est une valeur courte et unique qui identifie un appel API de bout en bout. Si les clients peuvent la voir dans chaque réponse, le support devient simple : « Envoyez-moi le request ID » suffit souvent pour trouver les logs exacts et l'échec exact.

Cette habitude rapporte aussi bien pour les réponses réussies que pour les erreurs.

Règles de génération et de propagation

Utilisez une règle claire : si le client envoie un ID, conservez-le. Sinon, créez-en un.

• Acceptez un ID entrant depuis un seul nom d'en-tête (choisissez-en un et documentez-le, par exemple X-Request-Id).
• Si l'en-tête manque ou est vide, générez un nouvel ID en périphérie (middleware) et attachez-le au contexte de la requête.
• Ne changez jamais l'ID en cours de requête. Transmettez-le aux appels en aval (DB, autres services) via le contexte ou des en-têtes.

Placez le request ID à trois endroits :

• En-tête de réponse (même nom d'en-tête que vous acceptez)
• Corps de réponse (comme request_id dans votre schéma standard)
• Logs (comme champ structuré sur chaque ligne de log)

Travaux batch et asynchrones

Pour les endpoints batch ou les jobs en arrière-plan, conservez un request ID parent. Exemple : un client téléverse 200 lignes, 12 échouent en validation, et vous mettez en file. Renvoyez un request_id pour l'appel global, et incluez un parent_request_id sur chaque job et chaque erreur par item. Ainsi, vous pouvez tracer « un seul upload » même quand il se déploie en de nombreuses tâches.

Logging et métriques sans divulguer d'internes

Les clients ont besoin d'une réponse d'erreur claire et stable. Vos logs ont besoin de la vérité complète et désordonnée. Séparez ces deux mondes : renvoyez un message public sûr et un code d'erreur public, tout en consignant la cause interne, la pile et le contexte côté serveur.

Consignez un événement structuré pour chaque réponse d'erreur, consultable par request_id.

Champs utiles à garder constants :

• request_id
• user_id ou account_id (si authentifié)
• code d'erreur public et statut HTTP
• nom du handler/route et méthode
• détail interne d'erreur (cause enveloppée, erreurs de validation, timeout en amont)

Stockez les détails internes seulement dans les logs serveur (ou un store d'erreurs interne). Le client ne doit jamais voir d'erreurs SQL brutes, de requêtes, de traces de pile ou de messages fournisseurs. Si vous exécutez plusieurs services, un champ interne comme source (api, db, auth, upstream) peut accélérer le triage.

Surveillez les endpoints bruyants et les erreurs de type rate-limit. Si un endpoint peut produire des milliers de 429 ou 400 par minute, évitez le spam de logs : échantillonnez les événements répétés, ou baissez leur sévérité tout en continuant de compter ces erreurs dans les métriques.

Les métriques détectent les problèmes plus tôt que les logs. Suivez les comptes groupés par statut HTTP et code d'erreur, et alertez sur des pics soudains. Si RATE_LIMITED augmente de 10x après un déploiement, vous le verrez rapidement même si les logs sont échantillonnés.

Étape par étape : implémenter un pipeline d'erreur cohérent en Go

La façon la plus simple de rendre les erreurs cohérentes est d'arrêter de les gérer « partout » et de les faire passer par un petit pipeline. Ce pipeline décide ce que le client voit et ce que vous conservez pour les logs.

Le pipeline en 5 étapes pratiques

Commencez par un petit ensemble de codes d'erreur sur lesquels les clients peuvent compter (par exemple : INVALID_ARGUMENT, NOT_FOUND, UNAUTHORIZED, CONFLICT, INTERNAL). Enveloppez-les dans une erreur typée qui n'expose que des champs publics sûrs (code, message sûr, détails optionnels comme quel champ est en erreur). Gardez les causes internes privées.

Puis implémentez une fonction de traduction qui transforme n'importe quelle erreur en (statusCode, responseBody). C'est là que les erreurs typées sont mappées aux statuts HTTP, et les erreurs inconnues deviennent une réponse 500 sûre.

Ensuite, ajoutez un middleware qui :

• garantit que chaque requête a un request_id
• récupère des panics

Un panic ne doit jamais déverser la trace de pile vers le client. Retournez une réponse 500 normale avec un message générique, et consignez le panic complet avec le même request_id.

Enfin, changez vos handlers pour qu'ils retournent une error au lieu d'écrire la réponse directement. Un wrapper peut appeler le handler, exécuter le traducteur et écrire du JSON dans le format standard.

Une checklist compacte :

• Définir des erreurs typées avec des champs publics sûrs et des codes stables.
• Traduire les erreurs en statuts et JSON de réponse en un seul endroit.
• Ajouter un middleware pour request ID et récupération de panic.
• Faire retourner des erreurs par les handlers, pas des réponses.
• Ajouter des tests golden pour le traducteur et le wrapper.

Les tests golden sont importants car ils verrouillent le contrat. Si quelqu'un change plus tard un message ou un statut, les tests échouent avant que les clients ne soient surpris.

Exemple : un endpoint, trois échecs, des réponses prévisibles

Imaginez un endpoint : une app cliente crée un enregistrement client.

POST /v1/customers avec JSON comme { "email": "[email protected]", "name": "Pat" }. Le serveur renvoie toujours la même forme d'erreur et inclut toujours un request_id.

1) Erreur de validation (400)

L'email est manquant ou mal formaté. Le client peut mettre en évidence le champ.

{
  "request_id": "req_01HV9N2K6Q7A3W1J9K8B",
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Some fields need attention.",
    "details": {
      "fields": {
        "email": "must be a valid email address"
      }
    }
  }
}

2) Conflit (409)

L'email existe déjà. Le client peut proposer de se connecter ou de choisir un autre email.

{
  "request_id": "req_01HV9N3C2D0F0M3Q7Z9R",
  "error": {
    "code": "ALREADY_EXISTS",
    "message": "A customer with this email already exists."
  }
}

3) Échec transitoire (503)

Une dépendance est indisponible. Le client peut réessayer avec backoff et afficher un message calme.

{
  "request_id": "req_01HV9N3X8P2J7T4N6C1D",
  "error": {
    "code": "TEMPORARILY_UNAVAILABLE",
    "message": "We could not save your request right now. Please try again."
  }
}

Avec un seul contrat, le client réagit de façon cohérente :

• 400 : marquer les champs en utilisant details.fields
• 409 : guider l'utilisateur vers une action sûre
• 503 : inviter au réessai et afficher le request_id comme identifiant de support

Pour le support, ce même request_id est le chemin le plus rapide vers la cause réelle dans les logs internes, sans exposer de traces de pile ou d'erreurs de base de données.

Pièges courants qui aggravent la gestion des erreurs

La façon la plus rapide d'ennuyer les clients API est de les faire deviner. Si un endpoint renvoie { "error": "..." } et un autre { "message": "..." }, chaque client devient un amas de cas spéciaux, et les bugs se cachent pendant des semaines.

Quelques erreurs reviennent souvent :

• Retourner HTTP 200 avec une erreur dans le corps, ou basculer entre plusieurs schémas d'erreur selon les endpoints.
• Exposer des internes dans le message utilisateur, comme des erreurs SQL, des traces de pile, des IPs, des noms d'hôtes de dépendances ou des chemins de fichiers.
• Utiliser du texte humain comme seul identifiant, au lieu d'un code stable sur lequel les clients peuvent se baser.
• Changer les codes d'erreur à la légère (ou réutiliser le même code pour des problèmes différents) et casser les clients.
• Ajouter request_id seulement sur les échecs, empêchant la corrélation d'un rapport utilisateur avec l'appel réussi qui a déclenché un problème ultérieur.

La fuite d'internes est le piège le plus simple : un handler renvoie err.Error() parce que c'est pratique, puis un nom de contrainte ou un message tiers finit dans une réponse en production. Gardez le message client sûr et court, et mettez la cause détaillée dans les logs.

Se baser uniquement sur du texte est un autre problème qui s'installe lentement. Si le client doit parser des phrases en anglais comme « email already exists », vous ne pouvez pas changer la formulation sans casser la logique. Les codes d'erreur stables vous permettent d'ajuster les messages, de les traduire et de conserver un comportement cohérent.

Considérez les codes d'erreur comme partie intégrante de votre contrat public. Si vous devez en changer un, ajoutez un nouveau code et conservez l'ancien en fonctionnement pendant un certain temps, même si les deux correspondent au même statut HTTP.

Enfin, incluez le même champ request_id dans chaque réponse, succès ou échec. Quand un utilisateur dit « ça marchait, puis ça a planté », cet ID sauve souvent une heure de recherche.

Checklist rapide avant la mise en production

Avant la release, faites une vérification rapide pour la cohérence :

• Une seule forme d'erreur partout. Chaque endpoint renvoie les mêmes champs JSON (par exemple : error.code, error.message, request_id).
• Codes d'erreur stables et couverts. Gardez des codes courts et sobres (VALIDATION_FAILED, NOT_FOUND, CONFLICT, UNAUTHORIZED). Ajoutez des tests pour empêcher les handlers de renvoyer des codes inconnus par accident.
• Une seule règle de mapping des statuts. Décidez comment chaque type d'erreur se mappe à un statut HTTP et appliquez-la en un endroit partagé.
• Request ID dans les deux sens. Retournez toujours un request_id et consignez-le pour chaque requête, y compris les panics et les timeouts.
• Messages sûrs par défaut. Les messages destinés aux utilisateurs doivent être courts, clairs et actionnables, jamais des traces de pile, des erreurs SQL ou des noms de fournisseurs.

Après cela, vérifiez manuellement quelques endpoints. Déclenchez une erreur de validation, un enregistrement manquant et une erreur inattendue. Si les réponses diffèrent selon les endpoints (champs qui changent, statuts incohérents, messages qui divulguent trop), corrigez le pipeline partagé avant d'ajouter plus de fonctionnalités.

Règle pratique : si un message aiderait un attaquant ou perturberait un utilisateur normal, il appartient aux logs, pas à la réponse.

Étapes suivantes : standardisez maintenant et maintenez la cohérence

Rédigez le contrat d'erreur que vous voulez que chaque endpoint suive, même si votre API est déjà en production. Un contrat partagé (statut, code d'erreur stable, message sûr et request_id) est le moyen le plus rapide de rendre les erreurs prévisibles pour les clients.

Ensuite, migrez progressivement. Conservez vos handlers existants, mais faites passer leurs échecs par un mappeur qui transforme les erreurs internes en votre forme publique. Cela améliore la cohérence sans un refactor risqué, et empêche les nouveaux endpoints d'inventer de nouveaux formats.

Gardez un petit catalogue de codes d'erreur et traitez-le comme partie de votre API. Quand quelqu'un veut ajouter un code, faites une revue rapide : est-ce vraiment nouveau, le nom est-il clair, et est-ce que ça mappe au bon statut HTTP ?

Ajoutez quelques tests pour détecter la dérive :

• Chaque réponse d'erreur inclut request_id.
• Le statut correspond au type d'erreur (pas au texte de l'erreur).
• error.code est présent et provient du catalogue.
• error.message reste sûr et n'inclut jamais de détails internes.
• Les erreurs inconnues retombent sur un 500 avec un message générique.

Si vous construisez un backend Go depuis zéro, il est utile de verrouiller le contrat tôt. Par exemple, Koder.ai (koder.ai) inclut un mode planning où vous pouvez définir des conventions comme un schéma d'erreur et un catalogue de codes en amont, puis garder les handlers alignés à mesure que l'API grandit.