Les codes de réponse HTTP

Le code 100 Continue indique que le début de la requête est accepté et que le client peut continuer à envoyer le corps de la requête.

Il est utile lorsqu’un client doit envoyer un corps volumineux. Le client peut d’abord demander si le serveur accepte les en-têtes avant d’envoyer une grande quantité de données.

Le code 101 Switching Protocols signifie que le serveur accepte de changer de protocole à la demande du client.

Il est notamment rencontré lors d’une montée en WebSocket. Le client demande une évolution de la connexion, et le serveur confirme qu’il bascule vers le nouveau protocole.

Le code 102 Processing indique que le serveur a reçu la requête et qu’il est en train de la traiter, mais qu’il n’a pas encore de réponse finale.

Il est principalement associé à WebDAV, où certaines opérations peuvent être longues ou porter sur plusieurs ressources. Il évite au client de penser que la requête est bloquée.

Le code 103 Early Hints permet au serveur d’envoyer des indications au client avant la réponse finale.

Il peut servir à annoncer des ressources à précharger, comme des feuilles de style, scripts ou polices. L’objectif est d’améliorer les performances en permettant au navigateur de commencer certains chargements plus tôt.

Le code 200 OK signifie que la requête a réussi. C’est le code de succès le plus courant.

Il est très fréquent avec GET lorsque le serveur retourne une ressource. Il peut aussi être utilisé après PUT ou PATCH si le serveur retourne la ressource modifiée dans la réponse.

Le code 201 Created indique qu’une nouvelle ressource a été créée. Il est typiquement utilisé après une requête POST.

La réponse devrait idéalement contenir un header Location indiquant l’URL de la ressource créée. Un PUT peut aussi retourner 201 s’il crée une ressource à l’URI demandée.

Le code 202 Accepted signifie que la requête a été acceptée, mais que son traitement n’est pas terminé.

Il est utile pour les traitements asynchrones : génération d’un rapport, import de données, envoi différé ou tâche placée dans une file d’attente. Le serveur confirme la prise en compte, mais pas encore le résultat final.

Le code 203 Non-Authoritative Information indique que la réponse est réussie, mais que certaines informations ont été modifiées par un intermédiaire.

Il peut apparaître avec des proxys ou passerelles qui transforment certaines métadonnées. Il est rare dans les API courantes, mais il rappelle que la réponse ne provient pas forcément exactement de la source originelle.

Le code 204 No Content signifie que la requête a réussi, mais que le serveur ne retourne aucun corps de réponse.

Il est courant après un DELETE, ou après un PUT ou PATCH lorsque le serveur confirme la modification sans renvoyer la ressource. Une réponse 204 ne doit pas contenir de contenu JSON.

Le code 205 Reset Content indique que la requête a réussi et que le client devrait réinitialiser l’interface qui a permis l’envoi.

Il peut être utilisé après l’envoi d’un formulaire pour signaler que les champs doivent être vidés. Il est beaucoup plus rare que 200, 201 ou 204.

Le code 206 Partial Content signifie que le serveur retourne seulement une partie de la ressource demandée.

Il est utilisé avec l’en-tête Range, par exemple pour reprendre un téléchargement interrompu ou lire une vidéo par fragments. Il est important pour le streaming et les fichiers volumineux.

Le code 207 Multi-Status permet de retourner plusieurs statuts dans une seule réponse.

Il est associé à WebDAV et aux opérations portant sur plusieurs ressources. Chaque ressource peut avoir son propre résultat, par exemple réussite pour l’une, échec pour une autre.

Le code 208 Already Reported indique qu’une ressource a déjà été mentionnée dans une réponse précédente.

Il est utilisé dans le contexte WebDAV pour éviter de répéter inutilement les mêmes informations dans une réponse complexe portant sur plusieurs ressources.

Le code 226 IM Used signifie que le serveur a appliqué des manipulations d’instance à la ressource avant de la retourner.

Il concerne des mécanismes HTTP avancés et très rarement rencontrés dans les applications classiques. Il peut être lié à des représentations transformées ou optimisées.

Le code 300 Multiple Choices indique que plusieurs réponses ou représentations sont possibles pour la même requête.

Le serveur peut fournir une liste de choix et laisser le client ou l’utilisateur sélectionner la représentation la plus adaptée : langue, format, version ou variante.

Le code 301 Moved Permanently indique que la ressource a été déplacée définitivement vers une autre URL.

Il est souvent utilisé pour les redirections SEO ou les changements définitifs d’adresse. Les navigateurs et moteurs de recherche peuvent mémoriser cette redirection.

Le code 302 Found indique que la ressource est temporairement disponible à une autre adresse.

L’URL initiale reste valide. Historiquement, certains clients changent la méthode en GET après une redirection 302. Pour conserver strictement la méthode, on préfère 307.

Le code 303 See Other indique au client de consulter une autre URL avec une requête GET.

Il est souvent utilisé après un POST, par exemple après la création ou la validation d’un formulaire, pour rediriger vers une page de confirmation ou vers la ressource créée.

Le code 304 Not Modified indique que la ressource n’a pas changé depuis la dernière version connue par le client.

Il est lié aux mécanismes de cache, comme ETag ou If-Modified-Since. Le client peut réutiliser sa version locale sans télécharger à nouveau la ressource.

Le code 305 Use Proxy indiquait qu’une ressource devait être consultée via un proxy.

Ce code est aujourd’hui déprécié pour des raisons de sécurité. Il ne doit pas être utilisé dans une application moderne.

Le code 307 Temporary Redirect indique une redirection temporaire vers une autre URL.

Contrairement à certains usages historiques du 302, le client doit conserver la méthode HTTP d’origine. Un POST reste donc un POST après redirection.

Le code 308 Permanent Redirect indique une redirection permanente vers une autre URL.

Comme 307, il conserve la méthode HTTP d’origine. Il est donc plus strict que 301 lorsqu’il faut garantir qu’un POST, PUT ou PATCH ne soit pas transformé en GET.

Le code 400 Bad Request signifie que le serveur ne peut pas comprendre ou traiter la requête telle qu’elle est envoyée.

Exemples fréquents : JSON invalide, paramètre dans un mauvais format, corps de requête absent alors qu’il est attendu, ou structure de données impossible à interpréter.

Le code 401 Unauthorized signifie que la requête nécessite une authentification valide.

Il est utilisé lorsque le client n’a pas fourni d’identifiants, a fourni un token invalide ou doit renouveler son authentification. La réponse peut contenir un header WWW-Authenticate.

Le code 402 Payment Required a été prévu historiquement pour des usages liés au paiement.

Il reste peu utilisé dans les applications courantes. Certaines plateformes peuvent l’utiliser pour signaler un abonnement expiré, un paiement nécessaire ou une limite commerciale atteinte.

Le code 403 Forbidden signifie que le serveur a compris la requête, mais refuse de l’autoriser.

Contrairement à 401, l’utilisateur peut être authentifié. Le problème est alors un manque de droits : rôle insuffisant, accès interdit ou ressource non autorisée.

Le code 404 Not Found signifie que la ressource demandée n’existe pas ou n’est pas accessible à cette URL.

Il peut s’agir d’une URL incorrecte, d’un identifiant inexistant ou d’une route non définie. Dans une API, c’est le code classique lorsqu’une ressource ciblée par son identifiant est introuvable.

Le code 405 Method Not Allowed signifie que l’URL existe, mais que la méthode HTTP utilisée n’est pas autorisée pour cette ressource.

Exemple : faire un POST sur une route qui accepte uniquement GET. Le serveur peut indiquer les méthodes acceptées avec le header Allow.

Le code 406 Not Acceptable signifie que le serveur ne peut pas produire une réponse dans un format acceptable pour le client.

Il est lié à la négociation de contenu, par exemple avec le header Accept. Si le client demande uniquement du XML et que le serveur ne fournit que du JSON, un 406 peut être approprié.

Le code 407 Proxy Authentication Required indique que le client doit s’authentifier auprès d’un proxy avant que la requête puisse être transmise.

Il ressemble à 401, mais concerne un proxy intermédiaire et non directement le serveur final. Il est rare dans une API applicative classique.

Le code 408 Request Timeout signifie que le client n’a pas envoyé la requête complète dans le délai attendu par le serveur.

Le serveur peut alors fermer la connexion. Cela peut arriver sur des connexions lentes, instables ou lorsqu’un client reste inactif trop longtemps.

Le code 409 Conflict indique que la requête entre en conflit avec l’état actuel de la ressource.

Il peut être utilisé lors d’un conflit de version, d’une tentative de création d’une ressource déjà existante, d’une modification concurrente ou d’une règle métier incompatible avec l’état actuel.

Le code 410 Gone indique que la ressource a existé, mais qu’elle n’est plus disponible.

Il est plus précis que 404 lorsque le serveur sait que la ressource a été supprimée définitivement. Il peut être utilisé pour des contenus retirés ou des endpoints abandonnés.

Le code 411 Length Required signifie que le serveur exige un header Content-Length.

Le client doit indiquer la taille du corps envoyé. Ce cas est rare avec les clients HTTP modernes, mais peut apparaître avec certains serveurs ou proxys stricts.

Le code 412 Precondition Failed signifie qu’une condition définie dans les headers de la requête n’est pas satisfaite.

Il est souvent lié aux requêtes conditionnelles, par exemple avec If-Match ou If-Unmodified-Since. Il peut servir à éviter d’écraser une ressource modifiée entre-temps.

Le code 413 Content Too Large indique que le corps de la requête dépasse la taille maximale acceptée par le serveur.

Il peut apparaître lors d’un upload de fichier trop volumineux, d’un JSON trop gros ou d’une limite configurée au niveau du serveur web, du proxy ou de l’application.

Le code 414 URI Too Long signifie que l’URL demandée est trop longue pour être traitée par le serveur.

Cela peut arriver avec des paramètres de requête excessifs ou des données placées à tort dans l’URL. Pour des données complexes, il vaut souvent mieux utiliser un corps de requête adapté.

Le code 415 Unsupported Media Type signifie que le format envoyé dans la requête n’est pas pris en charge.

Exemple : envoyer du XML alors que le serveur attend du JSON, ou oublier Content-Type: application/json lors de l’envoi d’un corps JSON.

Le code 416 Range Not Satisfiable indique que la plage demandée avec le header Range ne peut pas être fournie.

Cela peut arriver si le client demande une portion de fichier qui dépasse la taille réelle de la ressource.

Le code 417 Expectation Failed signifie que le serveur ne peut pas satisfaire l’attente exprimée dans le header Expect.

Il est rare dans les applications courantes, mais peut apparaître dans des échanges HTTP avancés où le client annonce une attente particulière avant d’envoyer la requête.

Le code 418 I'm a teapot est un code humoristique issu d’un poisson d’avril autour du protocole HTCPCP.

Il n’a pas d’usage normal dans une API de production, mais il est resté célèbre dans la culture web. Il est souvent utilisé comme clin d’œil technique.

Le code 421 Misdirected Request indique que la requête a été envoyée à un serveur qui ne peut pas produire une réponse correcte pour cette cible.

Il peut apparaître avec HTTP/2, des certificats partagés, des proxys ou des configurations d’hôtes virtuels lorsque la connexion est réutilisée vers le mauvais hôte.

Le code 422 Unprocessable Content signifie que la requête est syntaxiquement correcte, mais que son contenu ne peut pas être traité.

Il est très utile pour les erreurs de validation : champ obligatoire manquant, email invalide, valeur trop courte, date incohérente ou règle métier non respectée.

Le code 423 Locked indique que la ressource est verrouillée et ne peut pas être modifiée pour le moment.

Il est principalement associé à WebDAV, mais l’idée peut être utile pour comprendre les mécanismes de verrouillage, par exemple lorsqu’une ressource est en cours d’édition.

Le code 424 Failed Dependency signifie qu’une opération n’a pas pu être réalisée parce qu’une autre opération nécessaire a échoué.

Il est courant dans les traitements groupés ou WebDAV. Par exemple, si une première modification échoue, les opérations qui en dépendaient peuvent échouer aussi.

Le code 425 Too Early indique que le serveur refuse de traiter une requête envoyée trop tôt, car elle pourrait être rejouée.

Il est lié à des mécanismes de sécurité, notamment avec TLS 1.3 et les requêtes qui ne sont pas sûres à rejouer, comme certaines créations ou modifications.

Le code 426 Upgrade Required signifie que le serveur refuse la requête tant que le client n’utilise pas un protocole plus adapté.

Le serveur peut indiquer le protocole attendu avec le header Upgrade. Ce code peut être utilisé pour demander une version plus récente ou plus sécurisée.

Le code 428 Precondition Required indique que le serveur exige une requête conditionnelle.

Il sert notamment à éviter les pertes de mise à jour concurrentes. Par exemple, le serveur peut exiger un header If-Match pour vérifier que le client modifie bien la dernière version connue.

Le code 429 Too Many Requests indique que le client a envoyé trop de requêtes dans un intervalle de temps donné.

Il est utilisé pour limiter les abus, protéger un serveur ou appliquer une limite d’usage. La réponse peut contenir un header Retry-After indiquant quand le client pourra réessayer.

Le code 431 Request Header Fields Too Large signifie que les headers de la requête sont trop volumineux.

Cela peut venir d’un cookie trop grand, d’un token trop long ou d’un nombre excessif de headers. Le client doit réduire la taille des informations envoyées dans les en-têtes.

Le code 451 Unavailable For Legal Reasons indique que la ressource n’est pas disponible pour des raisons juridiques.

Il peut être utilisé lorsqu’un contenu est bloqué à la suite d’une obligation légale, d’une décision judiciaire ou d’une contrainte réglementaire.

Le code 500 Internal Server Error indique qu’une erreur inattendue s’est produite côté serveur.

C’est un code générique. Il ne faut pas l’utiliser pour masquer toutes les erreurs possibles si un code plus précis existe. En production, la réponse ne doit pas exposer d’informations techniques sensibles.

Le code 501 Not Implemented signifie que le serveur ne supporte pas la fonctionnalité nécessaire pour traiter la requête.

Il peut être utilisé si une méthode HTTP ou une capacité demandée n’est pas implémentée par le serveur. Ce n’est pas une erreur métier, mais une limite technique du serveur.

Le code 502 Bad Gateway indique qu’un serveur jouant le rôle de passerelle ou de proxy a reçu une réponse invalide d’un autre serveur.

On le rencontre souvent avec des reverse proxies, des API tierces, des services amont indisponibles ou des architectures où plusieurs serveurs communiquent entre eux.

Le code 503 Service Unavailable signifie que le serveur est temporairement indisponible.

Cela peut arriver lors d’une surcharge, d’une maintenance ou d’un redémarrage. La réponse peut contenir un header Retry-After pour indiquer quand le client pourra réessayer.

Le code 504 Gateway Timeout signifie qu’un serveur intermédiaire n’a pas reçu de réponse à temps d’un serveur en amont.

Il peut indiquer une API trop lente, une base de données saturée, un service externe indisponible ou un délai d’attente trop court dans la configuration du proxy.

Le code 505 HTTP Version Not Supported indique que le serveur ne prend pas en charge la version HTTP utilisée par le client.

Il peut apparaître si un client utilise une version obsolète, incorrecte ou non supportée du protocole HTTP.

Le code 506 Variant Also Negotiates indique une erreur de configuration dans la négociation de contenu.

Il est rare et concerne des cas avancés où une variante de ressource est elle-même configurée pour participer à la négociation, créant une situation incohérente.

Le code 507 Insufficient Storage signifie que le serveur ne dispose pas de l’espace nécessaire pour traiter la requête.

Il est associé à WebDAV, mais son sens reste clair : le serveur ne peut pas stocker la représentation ou les données nécessaires à l’opération.

Le code 508 Loop Detected indique que le serveur a détecté une boucle infinie pendant le traitement de la requête.

Il est surtout utilisé avec WebDAV, par exemple lorsqu’une structure de ressources contient une référence circulaire empêchant le traitement normal.

Le code 510 Not Extended indique que la requête nécessite des extensions supplémentaires non fournies ou non supportées.

Il est rare et concerne des mécanismes d’extension du protocole HTTP. Dans les API modernes, il est peu rencontré en pratique.

Le code 511 Network Authentication Required indique que le client doit s’authentifier auprès du réseau avant d’accéder à Internet ou à la ressource.

Il est typique des portails captifs, par exemple dans un hôtel, une gare, une école ou un réseau Wi-Fi public nécessitant une validation préalable.