Bien utiliser les codes de statut HTTP : le premier aiguillage du client

Ce que c'est

La RFC 9110 définit les cinq classes et les codes individuels ; un client doit reconnaître la classe au premier chiffre et traiter un code inconnu comme le code x00 de sa classe. Certaines distinctions comptent en pratique : 401 signifie des identifiants manquants ou invalides, et le serveur doit alors envoyer un en-tête WWW-Authenticate ; 403 signifie que l'authentification est correcte, mais que l'action n'est pas autorisée. 404 indique que la cible n'existe pas — ou que le serveur ne veut pas révéler son existence. 409 signale un conflit avec l'état actuel, 412 une condition préalable non satisfaite comme If-Match, 422 une requête syntaxiquement correcte mais dont le contenu ne peut pas être traité. La RFC 6585 ajoute 428 (condition préalable requise) et 429 (trop de requêtes), ce dernier pouvant être accompagné de Retry-After ; 503 signifie une indisponibilité temporaire, également accompagnée de Retry-After lorsque le temps d'attente est calculable.

Pourquoi c'est important

Un client voit le code avant d'analyser le corps ; les bibliothèques, les proxys et les caches n'aiguillent que sur cette base. Un 503 ou un 429 est réessayé par de nombreux clients, un 400 ou un 422 ne l'est pas ; un 304 évite le transfert, un 201 fournit l'adresse du nouvel élément créé. Un agent qui utilise une API à partir de sa documentation a besoin de cette convention pour ne pas avoir à deviner à chaque erreur — et pour ne pas réessayer, après un délai dépassé, une requête qui a déjà produit son effet.

Comment l'appliquer

• Associer chaque classe d'erreur du domaine à exactement un code et à un type de problème lisible par une machine ; ce tableau a sa place dans la documentation de l'API.
• Répondre à une création par 201 accompagné de Location ou de l'identifiant dans le corps ; répondre à une suppression ou une révocation réussie par 204 sans corps.
• Utiliser 400 pour les entrées syntaxiquement incorrectes, 422 pour celles dont le contenu est invalide — ou un seul des deux, mais de façon cohérente.
• Exiger des conditions préalables avec If-Match et des entity-tags, et répondre par 412 lorsqu'elles échouent ; qui veut les imposer répond par 428 aux requêtes dépourvues de condition préalable.
• Envoyer Retry-After avec 429 et 503 chaque fois que le temps d'attente est connu ; les clients et les agents s'y conforment au lieu de réessayer immédiatement.
• Utiliser 307 ou 308 pour les redirections dans les API, qui conservent la méthode et le corps ; avec 301 et 302, la RFC 9110 autorise un client, pour des raisons historiques, à transformer un POST en GET.

Pièges

Utiliser 404 pour dissimuler une décision d'autorisation est légitime, mais doit rester cohérent, sinon l'écart trahit l'existence de la ressource. Des codes propriétaires en dehors des plages enregistrées perturbent les intermédiaires. Un 200 avec {"error": ...} dans le corps est mis en cache, n'est pas réessayé, et est compté comme un succès par le monitoring.

Réussite partielle dans les requêtes par lots

Une requête qui traite plusieurs éléments produit plusieurs résultats. Le code de statut décrit la requête dans son ensemble : 200 (ou 207 Multi-Status selon la RFC 4918) si elle a été acceptée et traitée, 4xx uniquement si elle était invalide dans son ensemble. Chaque élément porte son propre statut et, le cas échéant, son propre objet de problème dans le corps de la réponse, à un emplacement documenté ; GraphQL procède de la même façon avec les erreurs de champ à côté de data. Le monitoring compte les erreurs d'éléments séparément des erreurs de requête, afin qu'un 200 avec quatre-vingt-dix pour cent d'éléments en échec ne passe pas pour un succès. Pour le reste, la règle de l'article demeure : une erreur qui touche la requête entière relève du code de statut, pas d'un 200.