Recherche Codes HTTP Status

Codes HTTP Status — Référence Complète de 100 à 511

Chaque réponse HTTP d'un serveur inclut un code à trois chiffres qui indique au client ce qui s'est passé. Les codes sont groupés en cinq catégories : 1xx (informationnel), 2xx (succès), 3xx (redirection), 4xx (erreur client), et 5xx (erreur serveur). Cette référence liste les 60+ codes enregistrés avec noms, descriptions, cas d'usage courants et liens vers les RFC qui les définissent. Filtrez par catégorie, cherchez par numéro ou mot-clé, ou copiez n'importe quel code dans votre presse-papiers pour la documentation, les rapports de bug ou les messages de commit.

Quelle est la différence entre 401 Unauthorized et 403 Forbidden ?

Les deux codes paraissent similaires mais signifient des choses différentes :

- **401 Unauthorized** — le client ne s'est pas authentifié, ou l'authentification a échoué. La solution est de se connecter ou d'envoyer un token valide. La réponse devrait inclure un header WWW-Authenticate disant au client comment. Malgré le nom, 401 signifie 'non authentifié'.

- **403 Forbidden** — le client est authentifié mais n'a pas la permission pour cette ressource spécifique. Aucune quantité de tentatives avec les mêmes identifiants ne le réparera ; l'utilisateur n'a simplement pas accès.

Un motif courant dans les applications sensibles à la sécurité est de retourner 404 Not Found au lieu de 403 pour éviter de révéler qu'une ressource restreinte existe même. Par exemple, GitHub retourne 404 pour les repos privés auxquels vous n'avez pas accès, pas 403.

Dois-je utiliser 301 ou 308 pour un redirect permanent ?

Cela dépend de la méthode HTTP. Les deux codes signifient la même chose sémantiquement (les deux sont des redirects permanents), mais se comportent différemment quand la requête originale était POST/PUT/DELETE :

- **301 Moved Permanently** — RFC 9110 permet explicitement aux clients de changer la méthode en GET en suivant un 301. Historiquement, la plupart des navigateurs faisaient toujours cela, même pour POST. N'utilisez 301 que pour les redirects GET.

- **308 Permanent Redirect** — préserve explicitement la méthode originale. POST reste POST, DELETE reste DELETE. Utilisez 308 quand le redirect doit fonctionner pour les endpoints API.

Pour les sites qui redirigent principalement des requêtes GET (par ex. HTTP → HTTPS, www → non-www), 301 convient et est légèrement mieux supporté par les anciens clients. Pour les APIs et formulaires, préférez 308.

La même distinction existe pour les redirects temporaires : 302 (lâche) vs. 307 (préserve la méthode).

Quand 422 Unprocessable Content est-il approprié ?

422 est le code correct quand la syntaxe de la requête est valide (JSON bien formé, content-type correct) mais le contenu *sémantique* est erroné. L'exemple classique est un formulaire d'inscription où :

- Le JSON parse correctement → ce n'est pas 400
- Le champ email est présent → ce n'est pas une erreur de champ manquant
- Mais l'adresse email est mal formée (par ex. 'not-an-email') → 422 Unprocessable Content

Vs. 400 Bad Request qui devrait être réservé pour :

- JSON malformé (erreur de parse)
- Champs requis manquants
- Header content-type incorrect

En pratique, beaucoup d'APIs utilisent 400 pour tout côté client, et c'est aussi acceptable. La distinction importe quand vous voulez donner aux clients un moyen programmatique de distinguer 'corriger vos données' de 'corriger le format de votre requête'. GitHub, Stripe et la plupart des APIs REST modernes utilisent 422 pour les erreurs de validation.

Quel est le bon code pour le rate limiting ?

**429 Too Many Requests** est la réponse canonique (RFC 6585). La réponse devrait inclure :

- Un header **Retry-After** — soit en secondes (`Retry-After: 60`), soit une date HTTP — indiquant au client quand réessayer.
- Un corps optionnel expliquant la limite. JSON comme `{"error": "rate_limit_exceeded", "retry_after": 60}` est courant.
- Un trio optionnel de headers **X-RateLimit-Limit**, **X-RateLimit-Remaining**, **X-RateLimit-Reset** pour que les clients suivent leurs quotas.

Pour la protection style DDoS où vous voulez abandonner la requête silencieusement, retourner 503 Service Unavailable avec un long Retry-After est parfois utilisé comme alternative.

Évitez d'utiliser 503 pour le rate-limiting normal car cela dit au client que le *serveur* échoue, pas le client. 429 est le bon signal que 'vous envoyez trop, ralentissez'.

418 'I'm a teapot' est-il réel ?

Oui, en quelque sorte. RFC 2324 définit le HyperText Coffee Pot Control Protocol (HTCPCP), un RFC du 1er avril de 1998 qui spécifiait des protocoles pour faire du café sur HTTP. Toute tentative de faire du café avec une théière retourne 418 I'm a teapot.

Le code est officiellement enregistré chez IANA mais réservé comme blague. En 2017 il y a eu une tentative semi-sérieuse de le retirer des bibliothèques serveur (Node.js l'a brièvement retiré) ; la communauté a poussé en retour et la plupart des stacks l'ont gardé.

Les cas d'usage réels pour 418 sont limités :

- **Blagues du 1er avril** — certains sites retournent 418 depuis un endpoint /teapot.
- **Easter eggs** dans la documentation API.
- **Détection de scrapers automatisés** — certains sites retournent 418 pour des patterns de trafic suspects.

N'utilisez pas 418 en production pour de vraies erreurs — les clients ne sauront pas quoi en faire.

Que signifie 503 et en quoi diffère-t-il de 500 ?

**500 Internal Server Error** est un catch-all générique : le serveur a heurté une condition inattendue (un bug, une exception non gérée) et n'a pas pu terminer la requête. L'implication est que réessayer immédiatement n'aidera probablement pas — quelque chose va mal côté serveur.

**503 Service Unavailable** est plus spécifique : le service est temporairement indisponible, généralement à cause de surcharge, maintenance planifiée ou lag d'autoscaling. L'implication est que réessayer plus tard (souvent avec le header **Retry-After** indiquant quand) réussira.

Quelques subtilités :

- Un load balancer retournant 503 signifie que l'upstream est inaccessible. Regardez les logs du LB.
- Une application retournant 503 signifie qu'elle rejette intentionnellement les requêtes (mode maintenance, circuit breaker déclenché).
- 503 ne devrait jamais être retourné par un crash d'app — c'est le territoire de 500.
- Cloudflare et autres CDNs ont leurs propres codes 5xx (520, 521, 522, 523, 524, 525, 526, 527) pour des erreurs upstream spécifiques.

Pourquoi la plage 1xx se voit-elle rarement dans les outils ?

Les codes 1xx sont intermédiaires — ils sont envoyés *avant* la réponse finale. La plupart des outils (navigateurs, curl, Postman) ne les exposent pas car au moment où la réponse finale 2xx/3xx/4xx/5xx arrive, le contexte 1xx est perdu.

Les trois que vous verrez occasionnellement :

- **100 Continue** — envoyé quand un client utilise `Expect: 100-continue` pour demander si le serveur acceptera un gros upload avant d'envoyer le corps.
- **101 Switching Protocols** — envoyé pendant une mise à niveau de protocole, le plus souvent le handshake WebSocket.
- **103 Early Hints** — plus récent (2017, RFC 8297). Permet au serveur d'envoyer des hints `Link: preload` avant la réponse finale, pour que le navigateur commence à télécharger CSS, JS et polices en parallèle. Utilisé par Cloudflare et Fastly.

102 Processing existe (RFC 2518 pour WebDAV) mais est à peine utilisé hors des serveurs WebDAV de niche.

D'où viennent ces codes ?

Les codes HTTP status sont définis à travers plusieurs RFCs :

- **RFC 9110** (juin 2024) — la spécification actuelle de sémantique HTTP, définissant les codes de base 1xx, 2xx, 3xx, 4xx, 5xx. A remplacé RFC 7231 en 2024.
- **RFC 4918** — WebDAV (207 Multi-Status, 422 Unprocessable Content [maintenant dans 9110], 423 Locked, 424 Failed Dependency, 507 Insufficient Storage).
- **RFC 6585** — Codes HTTP additionnels (428, 429, 431, 511).
- **RFC 7538** — 308 Permanent Redirect.
- **RFC 7725** — 451 Unavailable For Legal Reasons.
- **RFC 8297** — 103 Early Hints.
- **RFC 8470** — 425 Too Early (TLS 1.3).
- **RFC 2324** — 418 I'm a teapot (blague du 1er avril).
- **IANA HTTP Status Code Registry** — la liste autoritaire de tous les codes enregistrés.

Chaque carte dans cette référence lie au RFC qui définit ce code de status, pour que vous puissiez toujours aller à la source autoritaire pour les cas limites.

Caractéristiques Clés

• Chaque code HTTP status enregistré IANA (60+) couvrant 100 à 511
• Descriptions détaillées pour les 25 codes les plus courants (200, 301, 304, 401, 403, 404, 429, 500, 503, etc.)
• Recherche par numéro de code ou mot-clé à travers noms et descriptions
• Filtre par catégorie : 1xx Informationnel, 2xx Succès, 3xx Redirection, 4xx Erreur Client, 5xx Erreur Serveur
• Indicateurs de catégorie codés couleur pour reconnaissance visuelle instantanée
• Liens directs vers le RFC définissant pour chaque code (RFC 9110, RFC 6585, etc.)
• Boutons de saut rapide pour les quatre codes les plus recherchés (200, 301, 404, 500)
• Copiez n'importe quel code de status dans le presse-papiers en un clic pour rapports de bugs et documentation
• Exemples de cas d'usage expliquant quand chaque code est approprié
• Couvre les ajouts modernes : 103 Early Hints, 308 Permanent Redirect, 425 Too Early, 451 Legal
• Inclut 418 I'm a teapot de RFC 2324 pour l'exhaustivité
• JavaScript pur — aucune bibliothèque externe
• Fonctionne hors-ligne après le premier chargement
• Mise en page en grille responsive pour mobile et desktop
• 100% côté client — aucune requête n'est faite par la recherche