Codes de statut HTTP que tout développeur devrait connaître

Les codes de statut HTTP sont le langage que les serveurs utilisent pour indiquer aux clients ce qui s'est passé avec une requête. Tout développeur les rencontre constamment — dans les DevTools, les réponses d'API, les journaux d'erreurs, les alertes Slack à 3h du matin. Savoir ce que chaque code signifie réellement, quand utiliser quel code dans vos propres API, et ce que les plus courants signalent quant à un bug vous rend nettement plus rapide pour déboguer et construire de meilleurs services.

Vous pouvez consulter n'importe quel code de statut HTTP avec la Référence des codes de statut HTTP BrowseryTools — gratuit, sans inscription, tout s'exécute dans votre navigateur.

Les cinq catégories

Les codes de statut sont des nombres à trois chiffres. Le premier chiffre définit la catégorie :

• 1xx — Informationnel : La requête a été reçue ; le traitement continue. Ces codes sont rares dans la plupart des applications.
• 2xx — Succès : La requête a été reçue, comprise et acceptée.
• 3xx — Redirection : Une action supplémentaire est nécessaire pour compléter la requête. Le client doit suivre une redirection.
• 4xx — Erreur client : La requête était malformée ou non autorisée. C'est le client qui a fait une erreur.
• 5xx — Erreur serveur : Le serveur n'a pas pu répondre à une requête valide. C'est le serveur qui a fait une erreur.

Cette règle du premier chiffre est importante : si vous voyez un code de statut que vous ne connaissez pas (comme 429 ou 451), vous savez au moins si le problème vient du client ou du serveur, et si la requête a finalement abouti.

2xx : codes de succès

Ces codes indiquent au client que la requête a fonctionné. Le code spécifique précise comment :

• 200 OK — le succès universel. Le corps de la réponse contient les données demandées. Utilisé pour les requêtes GET et la plupart des réponses renvoyant du contenu.
• 201 Created — une nouvelle ressource a été créée. Doit inclure un en-tête Location pointant vers l'URL de la nouvelle ressource. À utiliser pour les requêtes POST qui créent des enregistrements, pas 200.
• 204 No Content — la requête a réussi mais il n'y a pas de corps à retourner. Courant pour les requêtes DELETE et les opérations PATCH/PUT où le client n'a pas besoin de recevoir les données mises à jour. La réponse ne doit pas inclure de corps.
• 206 Partial Content — utilisé avec les requêtes de plage (l'en-tête Range). Les lecteurs vidéo l'utilisent pour demander des plages d'octets spécifiques d'un fichier média sans télécharger le tout.

# REST API design pattern
POST   /api/users        → 201 Created  (body: new user object, Location: /api/users/123)
GET    /api/users/123    → 200 OK       (body: user object)
PATCH  /api/users/123    → 200 OK       (body: updated user) or 204 No Content
DELETE /api/users/123    → 204 No Content

3xx : codes de redirection

Les redirections indiquent au client de chercher ailleurs. L'en-tête Location contient la nouvelle URL. La distinction clé est entre les redirections permanentes et temporaires, et entre les redirections qui conservent la méthode HTTP et celles qui la changent.

• 301 Moved Permanently — la ressource a une nouvelle URL permanente. Les navigateurs et les moteurs de recherche mettent cela en cache. Le navigateur utilisera GET pour la redirection quelle que soit la méthode d'origine (une bizarrerie historique). À utiliser pour renommer définitivement une URL ou rediriger HTTP vers HTTPS dans une configuration ancienne.
• 302 Found — redirection temporaire. Comme le 301, les navigateurs changent POST en GET lors de la redirection (selon la spec, bien que la spec était « incorrecte » — voir 307). À utiliser uniquement quand la redirection est vraiment temporaire.
• 304 Not Modified — la version en cache est encore fraîche ; il n'y a pas de corps. Le serveur envoie cela en réponse à un GET conditionnel (avec If-None-Match ou If-Modified-Since). Le navigateur utilise sa copie en cache. Important pour l'efficacité des CDN et la réduction de la bande passante.
• 307 Temporary Redirect — comme le 302, mais la spec garantit que la méthode HTTP d'origine est préservée. Si un POST résulte en un 307, le navigateur fera un POST vers la nouvelle URL. Utilisez 307 à la place du 302 pour les redirections temporaires non-GET.
• 308 Permanent Redirect — comme le 301, mais garantit également la préservation de la méthode. Le standard moderne pour les redirections permanentes.

Idée reçue : 301 vs 302 pour le SEO

Les moteurs de recherche traitent le 301 comme un signal pour transférer le « capital de liens » (PageRank) de l'ancienne URL vers la nouvelle et mettre à jour leur index. Un 302 indique au robot d'indexation que la redirection est temporaire, il continue donc à indexer l'URL d'origine. Utiliser 302 quand vous voulez dire 301 peut supprimer le bénéfice SEO des redirections. À l'inverse, utiliser 301 quand la redirection est temporaire amène les moteurs de recherche à mettre la redirection en cache, rendant plus difficile son annulation.

4xx : codes d'erreur client

Ces codes indiquent que le client a envoyé une mauvaise requête. Ne retournez pas 5xx pour des erreurs client — cela induit en erreur la supervision et rend plus difficile l'identification d'un problème serveur vs une mauvaise entrée client.

• 400 Bad Request — la requête est malformée. Champs obligatoires manquants, JSON invalide, types de données incorrects. Le 4xx le plus générique ; utilisez des codes plus spécifiques quand ils existent.
• 401 Unauthorized — malgré son nom, cela signifie « non authentifié ». Le client n'a fourni aucune accréditation, ou les accréditations étaient invalides. La réponse doit inclure un en-tête WWW-Authenticate indiquant comment s'authentifier. Le nom est une erreur historique — « non authentifié » serait plus précis.
• 403 Forbidden — authentifié mais non autorisé. Le serveur sait qui vous êtes (ou peu importe qui vous êtes) et vous n'avez pas la permission. Contrairement au 401, se réauthentifier n'aidera pas. Utilisez 403 quand un utilisateur tente d'accéder à une ressource qu'il n'est pas autorisé à voir.
• 404 Not Found — la ressource n'existe pas à cette URL. Également retourné quand un serveur veut masquer l'existence d'une ressource aux utilisateurs non autorisés (retourner 403 confirmerait que la ressource existe ; retourner 404 masque ce fait).
• 409 Conflict — la requête est en conflit avec l'état actuel de la ressource. Exemple classique : essayer de créer un utilisateur avec une adresse e-mail qui existe déjà, ou essayer de mettre à jour une ressource avec une version obsolète (conflit de verrouillage optimiste).
• 422 Unprocessable Entity — la requête est syntaxiquement correcte (JSON valide, bon Content-Type) mais sémantiquement invalide (un champ obligatoire est présent mais contient une valeur invalide, violation d'une règle métier). Rails a popularisé l'utilisation du 422 pour les erreurs de validation. Plus spécifique que le 400.
• 429 Too Many Requests — limite de débit dépassée. Doit inclure un en-tête Retry-After indiquant au client combien de temps attendre. Indispensable pour toute API publique.

401 vs 403 : la distinction qui compte

C'est l'une des paires les plus souvent confondues :

GET /api/admin/users
Authorization: (none)
→ 401 Unauthorized
   "You haven't told me who you are. Log in first."

GET /api/admin/users
Authorization: Bearer <valid-regular-user-token>
→ 403 Forbidden
   "I know who you are. You're not an admin. Access denied."

5xx : codes d'erreur serveur

• 500 Internal Server Error — un fourre-tout générique pour les défaillances inattendues côté serveur. Une exception non gérée, une référence nulle, une requête de base de données qui a levé une erreur. N'exposez pas les traces de pile aux clients ; journalisez-les côté serveur.
• 502 Bad Gateway — le serveur agissant comme proxy ou passerelle a reçu une réponse invalide d'un serveur en amont. Courant quand votre répartiteur de charge ou proxy inverse ne peut pas atteindre les serveurs applicatifs derrière lui — l'application a planté ou n'écoute pas sur le bon port.
• 503 Service Unavailable — le serveur est temporairement incapable de traiter les requêtes. Il peut être surchargé, en cours de déploiement ou en maintenance. Doit inclure un en-tête Retry-After quand la durée de l'indisponibilité est connue.
• 504 Gateway Timeout — le proxy ou la passerelle n'a pas reçu de réponse dans les délais de la part du serveur en amont. L'upstream est actif mais répond trop lentement. Symptôme courant de requêtes de base de données qui prennent trop de temps ou d'appels à des API externes qui se bloquent.

Codes de statut dans la conception d'API REST

Utiliser les bons codes de statut rend votre API auto-documentée et plus facile à intégrer. Quelques recommandations :

• Ne renvoyez jamais 200 avec un objet d'erreur dans le corps. Si une requête a échoué, le code de statut doit le refléter. Les clients doivent pouvoir vérifier le code de statut seul pour savoir s'ils ont besoin de gérer une erreur.
• Utilisez 201 et un en-tête Location lors de la création de ressources via POST. Cela permet aux clients de découvrir l'URL de la nouvelle ressource sans analyser le corps.
• Retournez 422 (pas 400) pour les erreurs de validation, et incluez un corps d'erreur structuré qui identifie quels champs ont échoué et pourquoi.
• Utilisez 409 pour les conflits qui nécessitent une résolution au niveau applicatif, pas seulement une mauvaise entrée.
• Implémentez le 429 avec la limitation de débit dès le début sur tout endpoint public — il est bien plus difficile de l'ajouter après coup.

Déboguer les codes de statut dans les DevTools

Ouvrez l'onglet Réseau dans les DevTools du navigateur et cherchez les requêtes en rouge — ce sont des réponses 4xx ou 5xx. Cliquez sur une requête pour voir le code de statut exact, les en-têtes de réponse (utiles pour WWW-Authenticate, Location, Retry-After), et le corps de la réponse (qui contient souvent un message d'erreur du serveur). Pour les redirections, cochez « Conserver le journal » afin que le panneau DevTools ne s'efface pas lors de la navigation — sinon vous ratez la chaîne de redirections.

Lorsque vous rencontrez un code de statut inconnu, la Référence des codes de statut HTTP BrowseryTools vous donne la description officielle, la RFC dont il provient et des notes sur l'usage courant — sans avoir à quitter votre onglet navigateur.