Les codes d'erreur HTTP, et comment savoir lequel vous avez vraiment sous les yeux

Chaque erreur HTTP est une réponse d’une ligne à une question que personne n’a posée à voix haute : qu’est-il arrivé à ma requête ? Le nombre est toute la réponse, et il est délibérément laconique, si bien que l’essentiel du travail consiste à savoir à quelle question chaque nombre répond.

C’est à cela que sert cette page. Non pas une liste des soixante et quelques codes de statut, dont vous ne verrez jamais la plupart, mais la douzaine qui atteint réellement les gens, rangée selon ce qu’elle vous dit de l’endroit où la défaillance s’est produite.

La seule division qui compte

Le premier chiffre est la seule partie du code dont vous avez besoin de vous souvenir.

4xx

Le serveur vous a compris et refuse, ou n'a pas pu analyser ce qui est arrivé. Le problème est dans la requête

5xx

La requête était correcte. Le serveur n'a pas produit de réponse, ou a choisi de ne pas le faire

Tout le reste en découle. Une 4xx vous envoie regarder ce qui a été envoyé : l’URL, les en-têtes, le corps, les identifiants. Une 5xx vous envoie dans les journaux du serveur et, si ce n’est pas votre serveur, vous ne pouvez pas faire grand-chose de plus que de le signaler correctement.

Le mot « client » dans « erreur du client » est l’endroit où les gens se perdent, alors disons-le clairement : le client, ce n’est pas vous. Le client est le logiciel qui a composé la requête, et sur un site moderne c’est presque toujours le JavaScript de la page elle-même. Une 4xx sur le site de quelqu’un d’autre est généralement son bug portant votre nom.

Les codes 4xx que vous rencontrerez vraiment

400 Bad Request, c’est le serveur qui n’arrive pas du tout à analyser ce qui est arrivé. C’est le seul de cette famille qui porte sur la forme de la requête plutôt que sur la permission ou l’existence. Un corps mal formé, un content type manquant, une URL non échappée. Il en existe une seule version que vous puissiez corriger vous-même : un bloc de cookies devenu trop gros, ce qu’une fenêtre privée confirme en quelques secondes.

401 et 403 sont les deux que l’on intervertit constamment. 401 signifie que le serveur ne sait pas qui vous êtes et veut des identifiants. 403 signifie qu’il sait exactement qui vous êtes et que la réponse reste non. De meilleurs identifiants corrigent la première et jamais la seconde.

404 Not Found n’a pas besoin d’explication, mais une chose mérite d’être sue : une 404 sur une requête que la page a faite en arrière-plan, plutôt que dans la barre d’adresse, signifie généralement qu’un build ou un déploiement a perdu un fichier, et non que quelqu’un a mal tapé.

429 Too Many Requests est le seul code de statut qui porte sur votre comportement plutôt que sur le serveur ou la ressource. C’est aussi la seule erreur où réessayer aggrave les choses, parce qu’une nouvelle tentative est une requête de plus à compter pour le limiteur.

Les codes 5xx, qui se ressemblent et veulent dire des choses différentes

Tous les quatre disent « de notre côté », et les distinguer décide où l’on regarde en premier.

500 Internal Server Error

L'application a tourné et son propre code a échoué. Une exception non gérée. Elle a répondu, et la réponse était une erreur qu'elle a fabriquée elle-même

502 Bad Gateway

Un serveur de devant a reçu une réponse inutilisable de l'application derrière lui. La défaillance est entre deux serveurs

503 Service Unavailable

Quelque chose a choisi de ne pas vous servir. Maintenance, capacité, un limiteur de débit, ou rien de sain vers quoi router

504 Gateway Timeout

L'application n'a jamais répondu à temps. Le serveur de devant a cessé d'attendre

Le raccourci utile : une 500 est du code qui casse pendant qu’il tourne, une 502 est un proxy qui n’a pas obtenu de bonne réponse, une 504 est l’application trop lente, et une 503 est la seule qui est généralement intentionnelle. Cette dernière distinction compte plus qu’il n’y paraît : une 503 porte souvent un en-tête Retry-After disant exactement quand revenir, que presque personne ne lit.

Les erreurs qui ne sont pas du tout des codes de statut

Certaines des défaillances les plus courantes ne produisent jamais de code de statut, et c’est précisément pour cela qu’elles déroutent. La requête n’a pas échoué ; elle ne s’est jamais achevée.

TypeError: Failed to fetch est l’erreur la moins informative de JavaScript. Il n’y a pas de statut à lire parce que la requête n’est jamais allée assez loin pour en avoir un.

Les erreurs CORS sont le navigateur refusant de remettre à votre code une réponse qui est bel et bien arrivée. Le serveur a parfaitement répondu ; il n’a simplement pas dit que votre origine était autorisée.

ERR_CONNECTION_REFUSED, RESET, CLOSED et TIMED_OUT se produisent entièrement en dessous d’HTTP. Chacun nomme jusqu’où la connexion est allée avant de mourir, ce qui est l’essentiel d’un diagnostic offert.

Le contenu mixte est le navigateur bloquant une ressource non sécurisée sur une page sécurisée. Rien n’a échoué sur le réseau ; une règle a été appliquée.

En lire une qui n’est pas la vôtre

Si vous êtes visiteur plutôt que la personne qui peut corriger, trois vérifications séparent la plupart des cas et prennent moins d’une minute.

Rechargez une fois. Un bon nombre de 500 et de 503 sont un unique mauvais moment. Si cela se règle, il n’y a rien à poursuivre.

Essayez une fenêtre privée. C’est le test de la famille cookies et en-têtes : une 400 qui disparaît en navigation privée était un bloc de cookies trop gros, et une qui ne disparaît pas n’a jamais été la vôtre.

Essayez un autre réseau. Un téléphone en données mobiles répond à la question que pose un limiteur de débit. Si l’erreur vous suit partout, c’est votre compte ou le site ; si elle disparaît, c’était l’adresse d’où vous veniez. C’est la même question que distinguer votre bug de leur panne, posée rapidement.

Pourquoi le code seul suffit rarement à corriger quoi que ce soit

Chaque erreur ci-dessus est un résumé dont les preuves ont été retirées. Ce n’est pas un accident : une 500 est vague exprès, parce que la trace reste sur le serveur, et une 400 ne vous dira pas quel en-tête l’a offensée. Le code nomme la catégorie et tait le cas.

Donc « j’ai eu une 500 » est un signalement qui ne dit presque rien à un développeur et, le temps que quelqu’un enquête, la requête qui a échoué a disparu. Ce qui en referme une rapidement, c’est la requête défaillante elle-même, son heure exacte, et ce que la personne était en train de faire.

Le journal réseau est l’endroit où un code de statut cesse d’être une catégorie et devient un cas : la requête qui a reçu l’erreur, ses en-têtes et son corps, et la minute exacte, pour que celui qui la reprend puisse la confronter à un journal serveur au lieu de tout reproduire d’abord.

En un paragraphe

Le premier chiffre est la division qui compte : une 4xx signifie que le problème est dans la requête, une 5xx que le serveur n’a pas su répondre, et le « client » accusé par une 4xx est généralement le JavaScript du site plutôt que vous. Dans les 4xx, la 400 porte sur la forme de la requête, la 401 et la 403 sur l’identité contre la permission, et la 429 sur la fréquence à laquelle vous avez demandé. Dans les 5xx, la 500 est du code qui casse, la 502 un proxy avec une mauvaise réponse, la 504 rien qui réponde à temps, et la 503 la seule qui est généralement une décision. Les erreurs sans aucun code de statut, comme failed to fetch, CORS, ERR_CONNECTION_* ou le contenu mixte, sont celles qui déroutent le plus, parce que la requête ne s’est jamais achevée au lieu d’échouer. Quelle que soit la vôtre, le code nomme la catégorie et tait le cas : capturez donc la requête défaillante tant que vous l’avez.