03. Statuts et erreurs sans fuite

Comprendre le mécanisme

Les familles de statuts distinguent notamment succès, redirection, erreur liée à la demande et erreur de traitement serveur. Un code doit être interprété avec le contrat de l’API. Une réponse 202 peut annoncer une acceptation sans fin du traitement ; une réponse 204 ne transporte pas de contenu de représentation. Le statut ne remplace pas un modèle d’erreur ni les règles d’autorisation. Une erreur interne ne doit pas exposer une trace, une requête SQL ou les paramètres de connexion.

Raisonner et vérifier

Séparez messages publics stables et diagnostic privé corrélé. Ne transformez pas toutes les erreurs en 200 : les clients, caches et outils de supervision perdraient un signal important. Inversement, distinguez une donnée invalide d’une panne de dépendance pour permettre une reprise correcte. Une politique de non-divulgation peut harmoniser certaines réponses d’authentification, tout en conservant des événements minimisés utiles à l’investigation.

Accepté mais incomplet

202 peut annoncer un traitement encore incomplet. Acceptation et achèvement ne sont pas équivalents. 202 indique une acceptation sans garantir que le traitement est terminé. Fournissez un identifiant de suivi et des états documentés afin que le client ne confonde pas mise en queue et résultat final.

Réponse sans contenu

204 ne transporte pas de contenu de réponse. Le contrat de ce statut exclut le contenu. 204 exprime un succès sans contenu de réponse. N’ajoutez pas un JSON indispensable que le client devrait lire malgré ce statut ; choisissez un contrat cohérent entre statut et représentation.

Détails privés

Une erreur interne peut être corrélée en privé. Le diagnostic sensible ne doit pas être exposé. Une exception SQL peut contenir schéma, requête et paramètres. Retournez une erreur publique stable et conservez le diagnostic nécessaire dans un périmètre protégé, relié par une corrélation non sensible.

Codes stables

Un code d’erreur stable aide les clients. Une interface d’erreur doit fournir un contrat exploitable. Un code métier tel que capacity_exceeded permet un traitement client plus fiable qu’un texte humain variable. Versionnez le schéma d’erreur et évitez d’exposer directement les noms internes d’exceptions.

Signal de panne

Répondre 200 à toute panne masque un signal. Statuts et supervision doivent refléter le contrat. Retourner 200 avec un texte erreur peut faire considérer une panne comme un succès par cache, client ou supervision. Le statut doit rester cohérent avec le résultat réel du contrat.

Catégoriser

Un conflit métier peut différer d’une panne distante. La stratégie dépend de la cause et des effets possibles. Un conflit d’état local et une dépendance indisponible ne demandent pas nécessairement la même reprise. Définissez catégories et possibilités de retry ; ne transformez pas toute exception en réponse identique sans analyse.

Authentification uniforme

Une authentification invalide peut avoir un message public uniforme. Une politique de non-divulgation peut harmoniser les réponses. Une erreur publique peut éviter de distinguer compte absent et mauvais secret. Mesurez aussi chemins d’exécution et informations indirectes ; changer seulement le texte ne garantit pas une absence de divulgation.

RequestId

Un requestId public peut être non sensible. La corrélation ne nécessite pas un secret utilisateur. Un identifiant opaque permet de rechercher un incident sans publier la trace complète. Ne placez pas credentials ou données personnelles dans cet identifiant et validez les valeurs externes éventuellement propagées.

Tests de fuite

Le corps d’erreur doit être testé pour les secrets. Le statut ne filtre pas automatiquement le contenu. Provoquez une erreur avec une valeur factice identifiable puis vérifiez qu’elle n’apparaît pas dans le corps public. Contrôlez également les en-têtes et les pages générées par les couches intermédiaires.

Deux contrats

Un schéma public peut différer du diagnostic privé. Les publics et besoins d’accès sont différents. Le support technique peut avoir besoin d’une trace détaillée, tandis que le client reçoit une catégorie stable. Séparez accès et conservation de ces données pour garder un diagnostic utile sans divulgation publique.

Atelier guidé : lire, expliquer et vérifier le code

HTTP/1.1 202 Accepted
Content-Type: application/json

{"jobId":"lab-42","state":"queued"}

Le job est queued et la réponse est 202. Le client connaît une acceptation et une référence, mais pas la réussite de tous les effets métier. Définissez le mécanisme de suivi et testez les états ultérieurs, y compris échec après acceptation et absence de résultat encore disponible.

Les états sont différents. Le format ne prouve pas la progression métier. Le statut et l’état ne donnent pas la fin du traitement. Ce statut n’apporte pas cette garantie.

Travail pratique : Définissez cinq erreurs de votre portail : format invalide, refus de droit, conflit métier, dépassement de taille et dépendance indisponible.

Critères de correction : Associez chaque scénario à un statut et un schéma public. Simulez les erreurs et vérifiez que le corps ne contient pas de secret. Contrôlez aussi les chemins de log et la politique de reprise du client.