Référence des Codes de Statut HTTP

Explorez les codes de statut HTTP avec leurs descriptions.

http-status

Code	Name	Class	Meaning
100	Continue	Informational	The client should continue with its request.
101	Switching Protocols	Informational	The server is switching protocols as requested.
200	OK	Success	The request succeeded.
201	Created	Success	The request succeeded and a new resource was created.
202	Accepted	Success	The request was accepted but not yet processed.
204	No Content	Success	Success, but there is no content to return.
206	Partial Content	Success	The server delivered part of the resource (range request).
301	Moved Permanently	Redirection	The resource has permanently moved to a new URL.
302	Found	Redirection	The resource is temporarily at a different URL.
304	Not Modified	Redirection	The cached version is still valid.
307	Temporary Redirect	Redirection	Temporary redirect that preserves the method.
308	Permanent Redirect	Redirection	Permanent redirect that preserves the method.
400	Bad Request	Client Error	The server could not understand the request.
401	Unauthorized	Client Error	Authentication is required and has failed or not been provided.
403	Forbidden	Client Error	The server understood but refuses to authorize the request.
404	Not Found	Client Error	The requested resource could not be found.
405	Method Not Allowed	Client Error	The HTTP method is not supported for this resource.
408	Request Timeout	Client Error	The server timed out waiting for the request.
409	Conflict	Client Error	The request conflicts with the current state of the resource.
410	Gone	Client Error	The resource is permanently gone.
418	I'm a teapot	Client Error	An April Fools joke from RFC 2324.
422	Unprocessable Entity	Client Error	The request was well-formed but semantically invalid.
429	Too Many Requests	Client Error	The client has sent too many requests (rate limited).
500	Internal Server Error	Server Error	A generic server-side error occurred.
501	Not Implemented	Server Error	The server does not support the requested functionality.
502	Bad Gateway	Server Error	An upstream server returned an invalid response.
503	Service Unavailable	Server Error	The server is temporarily overloaded or down.
504	Gateway Timeout	Server Error	An upstream server did not respond in time.

§01 À PROPOS DE CET OUTIL

Vue d’ensemble

Un code d’état est le résumé en un mot que le serveur fait de ce qui s’est passé, et en choisir un mauvais a des conséquences bien au-delà de la propreté : cela change si les clients réessaient, si les caches stockent la réponse, si les robots conservent l’URL, et si un proxy traite la requête à nouveau.

Ceci est une référence consultable des codes que l’on rencontre réellement, avec pour chacun la distinction pratique plutôt qu’une reformulation de la spécification.

Utilisation

Tapez un numéro (404) ou une partie d’un nom (gateway) pour filtrer la liste. La correspondance porte sur les deux champs, si bien que too many et 429 trouvent la même entrée.

Les cinq classes

Classe	Signification	Ce qu’un client devrait faire
`1xx`	Information — la requête est encore en cours	Continuer d’attendre
`2xx`	Succès	Utiliser la réponse
`3xx`	Redirection — la ressource est ailleurs, ou inchangée	Suivre, ou utiliser le cache
`4xx`	Erreur du client — la requête elle-même est le problème	Ne pas réessayer sans la modifier
`5xx`	Erreur du serveur — la requête était peut-être correcte	Réessayer avec repli exponentiel

La séparation 4xx/5xx est celle qui compte le plus en pratique, parce qu’elle détermine le comportement de réessai. Un serveur qui renvoie 500 pour une requête mal formée se verra renvoyer cette même requête mal formée, encore et encore, par tout client bien élevé doté d’une politique de réessai. Renvoyer 400 arrête la boucle.

Les distinctions qui valent d’être bien faites

200 avec une erreur dans le corps. Courant dans les API et presque toujours une erreur. Chaque couche entre vous et le client — caches, proxys, supervision, logique de réessai — lit le code d’état, pas votre JSON. Une erreur qui renvoie 200 est invisible pour toutes ces couches.

201 contre 200 à la création. 201 devrait porter un en-tête Location pointant vers la nouvelle ressource. C’est cette partie que les clients utilisent ; le code seul n’apporte pas grand-chose.

202 Accepted. La bonne réponse pour un travail que vous avez mis en file d’attente plutôt qu’exécuté. C’est une promesse, elle doit donc dire au client où aller vérifier — une URL de statut, ou un identifiant de tâche.

204 No Content. Un succès au corps intentionnellement vide, typiquement pour un DELETE ou un PUT qui ne renvoie rien. Il ne doit avoir aucun corps du tout, pas un objet JSON vide.

304 Not Modified. La réponse à une requête conditionnelle dont l’ETag ou le Last-Modified correspond toujours. Elle ne porte aucun corps, et c’est tout l’intérêt : le client a déjà les octets. Si vous ne renvoyez jamais 304, chaque revalidation retransfère la ressource entière.

400 contre 422. 400 pour une requête que le serveur n’a pas pu analyser — JSON mal formé, paramètre obligatoire manquant. 422 pour une requête qui s’est analysée proprement et a échoué à la validation. La distinction indique au client s’il doit corriger sa sérialisation ou ses données.

405 Method Not Allowed. Doit inclure un en-tête Allow listant les méthodes qui sont acceptées. Sans lui, on a dit non au client sans lui laisser d’issue.

409 Conflict. Pour une requête qui ne peut pas être appliquée à l’état courant — une modification portant sur une version périmée, un doublon qui viole une contrainte d’unicité. Pas un « quelque chose n’allait pas » générique.

410 Gone. Un 404 plus affirmé : cela a existé et ne reviendra pas. Les robots abandonnent un 410 plus vite qu’un 404, ce qui est exactement ce que vous voulez pour un contenu que vous avez délibérément retiré.

429 Too Many Requests. A besoin de Retry-After. Sans lui, les clients devinent, et ils devinent mal — généralement en réessayant immédiatement.

502 contre 503 contre 504. 502 signifie qu’un service en amont a donné une réponse invalide. 503 signifie que ce serveur-ci est indisponible, typiquement surchargé ou en maintenance. 504 signifie qu’un service en amont n’a pas répondu à temps. Ils désignent trois endroits différents, et les employer indifféremment rend une panne plus difficile à localiser.

Exemples

Un robot continue de demander une page supprimée. Renvoyez 410 plutôt que 404.
Un client martèle un point d’entrée en échec. Vérifiez si l’échec renvoie du 5xx pour ce qui est en réalité une condition 4xx.
La soumission d’un formulaire perd ses données derrière une redirection. La redirection est probablement un 301 ou un 302 ; passez à 308 ou 307.
Un CDN refuse de mettre une réponse en cache. Les 2xx et 3xx sont cachables par défaut ; la plupart des 4xx ne le sont pas, et les 5xx ne devraient jamais l’être.
Une API renvoie 200 et les clients ignorent l’échec. Ils ne l’ignorent pas — rien ne leur a rien dit.

Remarques

418 I'm a teapot est réel, dans le sens où il est enregistré et réservé de façon permanente. Il vient d’une RFC du 1er avril et figure dans la liste parce que les gens le cherchent.

Les codes hors du registre sont légaux. Un client doit traiter tout code inconnu selon sa classe, si bien qu’un 299 maison est traité comme un succès et un 599 maison comme une erreur de serveur. En utiliser un vaut rarement la confusion que cela crée.

La liste présentée ici couvre les codes réellement en usage. Le registre complet est maintenu par l’IANA et comprend des codes pour WebDAV et d’autres extensions qu’un service web ordinaire ne renvoie jamais.

Pour voir quels codes une URL en production renvoie effectivement, chaîne de redirections comprise, utilisez le vérificateur d’en-têtes HTTP.

FAQ

Cet outil envoie-t-il quoi que ce soit ?

Non. La liste des codes fait partie de la page. Elle fonctionne hors ligne une fois chargée, et rien de ce que vous tapez ne quitte votre navigateur.

Quelle est la différence entre 401 et 403 ?

401 signifie que la requête n'était pas authentifiée — le serveur ne sait pas qui vous êtes, et un identifiant valide changerait la réponse. 403 signifie qu'il le sait et que la réponse est quand même non. Un 401 doit inclure un en-tête WWW-Authenticate indiquant comment s'authentifier ; un 403 n'a rien à proposer.

Quand utiliser 404 plutôt que 403 ?

Utilisez 404 quand reconnaître l'existence de la ressource divulguerait en soi une information. Renvoyer 403 pour /users/42 apprend à un attaquant que l'utilisateur 42 existe ; 404 non. C'est un mensonge délibéré, et c'est le bon pour les ressources sensibles du point de vue des autorisations.

Quelles redirections préservent la méthode de la requête ?

307 et 308. Les clients ont historiquement converti POST en GET en suivant 301 et 302, et ce comportement reste répandu : utilisez donc 308 pour un déplacement permanent et 307 pour un déplacement temporaire dès qu'un POST peut être impliqué.

429 est-il la même chose que 503 ?

Non. 429 signifie que ce client a envoyé trop de requêtes et devrait ralentir. 503 signifie que le serveur dans son ensemble ne peut servir personne pour l'instant. Les deux devraient porter Retry-After, et les confondre fait mal se comporter le repli exponentiel des clients.