Recherche de code de statut HTTP

Le référentiel des codes de statut HTTP offre un accès instantané aux explications détaillées de chaque code de réponse HTTP de 100 à 599, incluant les références RFC, les cas d'utilisation courants et les distinctions subtiles entre les codes fréquemment confondus. Saisissez un code comme 403 ou recherchez par mot-clé comme "redirect" pour obtenir le nom officiel, la signification et des recommandations pratiques pour son utilisation dans vos propres API.

Comprendre les codes de statut HTTP

Chaque réponse HTTP commence par un code de statut à trois chiffres qui indique au client ce qui s'est passé avec sa requête. Si vous avez déjà vu une page 404, reçu une erreur 500 d'une API, ou été silencieusement redirigé par un 301, vous avez rencontré les codes de statut en action. Ils sont la première chose que votre navigateur, client HTTP ou système de monitoring vérifie lorsqu'une réponse arrive, et choisir le bon code dans vos propres API est essentiel pour construire des systèmes qui se comportent de manière prévisible et sont faciles à déboguer.

Les codes de statut sont regroupés en cinq classes selon leur premier chiffre. Les codes 1xx sont informatifs -- le serveur accuse réception de la requête mais n'a pas fini de la traiter. Les codes 2xx indiquent le succès -- la requête a été reçue, comprise et traitée correctement. Les codes 3xx gèrent les redirections -- le client doit effectuer une action supplémentaire, généralement suivre une nouvelle URL. Les codes 4xx signalent des erreurs client -- la requête était malformée, non autorisée, ou pointait vers quelque chose qui n'existe pas. Et les codes 5xx indiquent des erreurs serveur -- le serveur a compris la requête mais n'a pas réussi à la traiter en raison d'un problème interne.

La difficulté ne réside pas dans le fait de savoir que 200 signifie succès ou que 404 signifie non trouvé -- ceux-là sont bien connus. La vraie complexité se trouve dans les distinctions subtiles. Devriez-vous utiliser 401 ou 403 quand un utilisateur n'a pas les permissions ? 301 ou 308 est-il la bonne redirection pour un endpoint POST qui a été déplacé ? Une recherche sans résultat devrait-elle retourner 200 avec un corps vide, 204, ou 404 ? Cet outil explique ces distinctions avec des recommandations pratiques pour que vous puissiez faire le bon choix selon votre cas d'utilisation spécifique.

Comment rechercher un code de statut HTTP

1. Saisissez un numéro de code de statut (par ex. 404) ou recherchez par mot-clé (par ex. "redirect", "unauthorized").
2. Consultez le nom officiel, la référence RFC et l'explication détaillée.
3. Lisez les recommandations d'utilisation pour savoir quand retourner ce code dans votre propre API.

Référence rapide des codes de statut HTTP

Information (1xx)

Succès (2xx)

Redirection (3xx)

Erreur client (4xx)

Erreur serveur (5xx)

Codes de statut fréquemment confondus

301 vs. 302 vs. 307 vs. 308

• 301 Moved Permanently -- À utiliser lorsque l'URL d'une ressource a changé définitivement. Les navigateurs et moteurs de recherche peuvent transformer un POST en GET lors de la redirection.
• 302 Found -- Redirection temporaire. Historiquement, les navigateurs transformaient POST en GET malgré la spécification qui l'interdisait. Ambigu en pratique.
• 307 Temporary Redirect -- Comme 302, mais le navigateur doit conserver la méthode HTTP d'origine (POST reste POST).
• 308 Permanent Redirect -- Comme 301, mais le navigateur doit conserver la méthode HTTP d'origine. À utiliser au lieu de 301 lors de la redirection de soumissions de formulaires.

401 vs. 403

• 401 Unauthorized -- Le client n'a pas fourni d'identifiants d'authentification valides. La réponse doit inclure un en-tête WWW-Authenticate indiquant le schéma d'authentification attendu.
• 403 Forbidden -- Le client est authentifié (ou l'authentification n'est pas requise), mais n'a pas la permission d'accéder à la ressource. Se ré-authentifier ne résoudra pas le problème.

404 vs. 410

• 404 Not Found -- La ressource n'est pas disponible. Elle peut n'avoir jamais existé, ou peut exister dans le futur.
• 410 Gone -- La ressource existait auparavant mais a été intentionnellement et définitivement supprimée. Les moteurs de recherche désindexent l'URL plus rapidement avec 410 qu'avec 404.

500 vs. 502 vs. 503 vs. 504

• 500 -- Le serveur lui-même a rencontré une erreur lors du traitement de la requête (exception non gérée, bug).
• 502 -- Un reverse proxy ou load balancer a reçu une réponse invalide d'un serveur en amont.
• 503 -- Le serveur est temporairement dans l'incapacité de traiter les requêtes (surchargé, en maintenance). Inclut souvent un en-tête Retry-After.
• 504 -- Un reverse proxy ou load balancer a expiré en attendant la réponse d'un serveur en amont.

Quand utiliser cet outil

• Conception d'API RESTful -- Choisissez des codes de statut sémantiquement corrects pour chaque endpoint et condition d'erreur.
• Débogage de réponses API -- Comprenez la signification d'un code de statut inconnu ou inattendu dans les logs serveur.
• Gestion des redirections -- Déterminez s'il faut utiliser 301, 302, 307 ou 308 pour votre scénario de redirection spécifique.
• Configuration des alertes de monitoring -- Mettez en place des alertes pour des codes de statut spécifiques en comprenant ce que chacun indique.
• Optimisation SEO -- Utilisez les bons codes de redirection (301 vs 302) pour préserver le référencement lors des migrations d'URL.
• Triage d'incidents -- Identifiez rapidement si une erreur 5xx provient de votre application (500) ou de l'infrastructure (502, 504).

Recommandations pratiques pour les codes de statut API

L'une des erreurs les plus courantes en conception d'API est de surexploiter 200 OK pour tout, y compris les erreurs. Certaines API retournent 200 avec un message d'erreur dans le corps, forçant le client à analyser la réponse pour déterminer si la requête a réellement réussi. Cela casse les outils HTTP standard, rend le monitoring peu fiable et désoriente les développeurs qui s'attendent à ce que les codes de statut HTTP reflètent le résultat réel. Utilisez 200 pour le succès, 4xx pour les erreurs client et 5xx pour les erreurs serveur -- c'est à cela que servent ces codes.

Une autre source fréquente de confusion est le choix entre 404 et des réponses de succès vides. Si un utilisateur recherche des produits et que la recherche ne retourne aucun résultat, la bonne réponse est 200 avec un tableau vide -- le endpoint de recherche existe, il a fonctionné, et il n'a rien trouvé. Si l'utilisateur demande un produit spécifique par ID et que ce produit n'existe pas, la bonne réponse est 404 -- la ressource demandée n'est pas là. La distinction est entre "j'ai fait ce que vous avez demandé et la réponse est rien" (200) versus "ce que vous cherchez n'existe pas" (404).

Pour les API qui servent à la fois des utilisateurs authentifiés et non authentifiés, faites attention aux informations que vous divulguez à travers les codes de statut. Répondre avec 403 à une requête non autorisée vers /admin/users confirme que le endpoint existe. Répondre avec 404 à la place ne révèle rien sur la structure de vos URL. La communauté sécurité appelle cela la "sécurité par l'obscurité" et cela a ses limites, mais c'est une mesure de défense en profondeur raisonnable pour les endpoints sensibles.

Questions fréquentes

Quels sont les codes de statut 5xx personnalisés de CloudFlare ?

CloudFlare utilise les codes 520 à 527 pour les problèmes entre ses serveurs edge et les serveurs d'origine. Par exemple, 520 signifie que l'origine a retourné une réponse inattendue, 521 signifie que le serveur web d'origine est hors service, 522 signifie que la connexion vers l'origine a expiré, et 524 signifie que l'origine a répondu mais a pris trop de temps.

Y a-t-il une différence entre "Unauthorized" et "Unauthenticated" ?

Techniquement, le code HTTP 401 devrait s'appeler "Unauthenticated" car il signifie que le client n'a pas prouvé son identité. Le nom "Unauthorized" est un abus de langage historique dans la spécification. La véritable erreur d'autorisation (vous êtes authentifié mais n'avez pas les droits) correspond au code 403 Forbidden.

Faut-il utiliser 404 ou 204 quand une recherche ne retourne aucun résultat ?

Utilisez 200 avec un ensemble de résultats vide. La ressource (le endpoint de recherche) existe et a répondu avec succès -- elle n'a simplement trouvé aucun élément correspondant. Réservez 404 aux cas où le endpoint lui-même n'existe pas.

Quand dois-je utiliser 429 Too Many Requests ?

Utilisez 429 lorsqu'un client a dépassé la limite de débit de votre API. Incluez un en-tête Retry-After indiquant combien de secondes le client doit attendre avant de réessayer. Ajoutez également les en-têtes X-RateLimit-Limit et X-RateLimit-Remaining pour que les clients puissent voir leur quota actuel sans atteindre la limite.

Quelle est la différence entre 502 et 504 dans une configuration reverse proxy ?

Un 502 Bad Gateway signifie que le proxy a reçu une réponse du serveur en amont, mais cette réponse était invalide ou malformée (par exemple, le serveur en amont a renvoyé des données corrompues ou a fermé la connexion en cours de réponse). Un 504 Gateway Timeout signifie que le proxy n'a jamais reçu de réponse -- le serveur en amont n'a pas répondu dans le délai configuré. Les deux indiquent des problèmes en amont, mais 504 suggère généralement que le serveur est surchargé ou injoignable, tandis que 502 suggère qu'il répond mais se comporte incorrectement.

Dois-je retourner 201 Created ou 200 OK après la création d'une ressource ?

Utilisez 201 Created pour les requêtes POST qui créent une nouvelle ressource. Incluez un en-tête Location pointant vers l'URL de la ressource nouvellement créée. Cela suit les conventions REST et aide les clients à localiser la nouvelle ressource sans analyser le corps de la réponse. Utilisez 200 pour les mises à jour de ressources existantes (PUT/PATCH).

Outils associés

• HTTP Header Formatter - Analyser et formater les en-têtes de réponse HTTP qui accompagnent les codes de statut
• CORS Header Explainer - Comprendre les erreurs CORS qui produisent des codes de statut spécifiques
• MIME Type Lookup - Rechercher les en-têtes Content-Type retournés avec les réponses HTTP
• Cookie Header Parser - Analyser les en-têtes Set-Cookie des réponses HTTP
• curl Command Builder - Construire des commandes curl pour tester les endpoints et inspecter les codes de statut