Guide complet des codes de statut HTTP
Arrêtez de deviner 401 vs 403 : un tour d’horizon orienté dev de chaque famille de statuts, avec exemples réalistes, anti-patterns et les codes qui comptent vraiment pour le SEO.
D’autres utilitaires qui complètent bien ce guide :
Pourquoi c’est important
Un backend renvoie 200 OK avec {"error": "Unauthorized"} dans le corps. Le gestionnaire d’erreur front le traite comme un succès parce que le statut était 200. Le formulaire de connexion boucle. De petites erreurs de statut coûtent des heures d’ingénierie — et faussent le crawl SEO et le suivi des liens cassés. Savoir quel code envoyer et quand, c’est partie intégrante du métier.
Trois scénarios réels
Pas de jeton ? 401. Jeton sans droit ? 403. La ressource n’existe tout simplement pas ? 404.
Comportement client prévisible
Le 301 conserve le PageRank ; le 302 signale temporaire, sans transfert. Choisissez consciemment.
Redirection permanente, transfert du classement
Un 503 avec en-tête Retry-After dit aux crawlers de revenir plus tard plutôt que de déréférencer.
Les moteurs savent réessayer
Les cinq familles en un coup d’œil
| Plage | Famille | Membres courants |
|---|---|---|
| 1xx | Information | 100 Continue, 101 Switching Protocols |
| 2xx | Succès | 200 OK, 201 Created, 204 No Content |
| 3xx | Redirection | 301, 302, 304 Not Modified, 308 |
| 4xx | Erreur client | 400, 401, 403, 404, 422, 429 |
| 5xx | Erreur serveur | 500, 502, 503, 504 |
Parcours — utiliser la référence
Ouvrez la référence des codes HTTP.
Rechercher par code ou description
Tapez « 401 », « unauthorized » ou « rate limit ». Les codes correspondants remontent en tête.
Lire la signification canonique
Chaque entrée explique ce que dit la spec, pas seulement ce qu’affiche curl.
Voir l’usage réel
Les notes signalent où des API populaires (GitHub, Stripe, AWS) divergent légèrement.
Repérer l’impact SEO
Chaque code est balisé selon le traitement moteur (indexable ou non, transfert de rang ou non).
Copier une phrase type
Collez la description dans votre doc API ou en commentaire inline.
Scénario
POST /admin/users
(No Authorization header)Réponse recommandée
401 Unauthorized
WWW-Authenticate: Bearer realm="admin"Scénario
POST /admin/users
Authorization: Bearer eyJ... (valid token, viewer scope)Réponse recommandée
403 Forbidden
{"error": "scope_admin_required"}
Conseils avancés
- Utilisez 422 pour une entrée « bien formée mais sémantiquement invalide » (ex. JSON avec mauvais types de champs). Le 400 est pour les requêtes mal formées.
- 204 No Content pour les suppressions est plus propre qu’un 200 avec corps vide — le client sait qu’il n’y a pas de charge utile volontaire.
- Toujours inclure
Retry-Afteravec 429 / 503. Les clients avancés savent exactement quand revenir. - Évitez le 200 avec
error: ...dans le corps. Ça vide de sens les codes HTTP et trompe tous les outils de supervision.
Pièges courants
Piège courant
Renvoyer 404 pour « vous n’y avez pas accès »
Un 404 flou dissimule l’existence — parfois voulu (ex. dépôts privés), mais pour des API authentifiées classiques préférez 403 pour que le client comprenne que c’est une question d’autorisation.
Piège courant
Mettre un 302 en cache pour toujours
Le 302 est temporaire par spec, mais certains intermédiaires mettent en cache agressivement. Si la redirection est permanente, envoyez 301 (ou 308 pour conserver la méthode).
Piège courant
Renvoyer 500 pour des erreurs client
Le 500, c’est serveur. Si le client a envoyé des données invalides, renvoyez un 4xx — sinon votre alerting crie à un bug chez eux.
Quand ce n’est pas l’outil adapté
- Concevoir un tout nouveau protocole — les codes HTTP sont liés à HTTP ; gRPC, WebSockets et protocoles propriétaires ont leurs conventions.
- Rapport d’erreur applicatif — les codes d’erreur métier vont dans le corps avec le code HTTP.
- Supervision — votre APM doit catégoriser les statuts automatiquement ; cette référence sert aux décisions de conception avant livraison.
FAQ
Quelle différence entre 301 et 308 ?
Les deux sont des redirections permanentes. Le 308 garantit la conservation de la méthode HTTP ; le 301 a historiquement permis aux clients de passer POST → GET au suivi.
Le 418 « I'm a teapot » est sérieux ?
Oui, RFC 2324 (1er avril 1998), réaffirmé dans RFC 7168. C’est une blague, pas utilisée en production.
Dois-je exposer des codes spécifiques à un framework (419, 440) ?
Évitez si possible. Restez sur l’ensemble enregistré IANA pour que les clients génériques comprennent.
Étapes suivantes
- Inspectez les réponses avec l’analyseur d’URL en cas de comportement étrange.
- Pour Git ou Linux pendant le triage, voyez les références commandes Git et Linux.
- Vérifiez IP/ASN du serveur avec l’outil IP quand les 502/504 pointent vers l’amont.