Codes de statut 4xx expliqués : ce que signifient les erreurs client

Ce que signifie la classe 4xx

La RFC 9110 définit la classe 4xx comme « Client Error » : le serveur estime que le client a commis une erreur. Cela couvre une requête pour quelque chose qui n'existe pas, une requête sans les identifiants requis, une requête que le serveur refuse pour des raisons de politique, et une requête mal formée ou trop volumineuse.

Trois propriétés de la classe comptent pendant que vous en déboguez une :

• Un 4xx est une réponse définitive pour cette requête telle qu'envoyée. Répéter la requête identique produira normalement le même code.
• Le corps de la réponse est censé être une explication lisible par un humain. C'est pourquoi des pages d'erreur personnalisées existent, et pourquoi une page 404 vide est une occasion manquée.
• Certaines réponses 4xx sont cachables par défaut. La RFC 9111 liste 404, 405, 410 et 414 parmi les codes qu'un cache peut stocker de façon heuristique, donc un 404 erroné peut survivre au bug qui l'a causé.

Les codes 4xx que vous rencontrerez

• 400 Bad Request : la requête est mal formée et le serveur ne peut pas l'analyser. Souvent une chaîne de requête invalide, un en-tête de cookie surdimensionné ou un proxy cassé devant l'application.
• 401 Unauthorized : une authentification est requise et est soit absente, soit invalide. Le serveur doit envoyer un en-tête WWW-Authenticate indiquant au client comment s'authentifier.
• 403 Forbidden : le serveur a compris la requête et la refuse. Des identifiants n'aideront pas, car le refus est une décision de politique plutôt qu'un échec d'authentification.
• 404 Not Found : aucune représentation actuelle n'existe à cette URL, ou le serveur ne veut pas admettre qu'il y en a une. Traité en détail dans le guide du 404.
• 405 Method Not Allowed : l'URL existe mais pas pour cette méthode. Le serveur doit lister les méthodes qu'il accepte dans un en-tête Allow.
• 408 Request Timeout : le client a pris trop de temps pour envoyer la requête. Différent d'un 504, où le délai vient de derrière le serveur.
• 410 Gone : la ressource existait et a été délibérément supprimée, et cela est censé être permanent.
• 413 Content Too Large et 414 URI Too Long : la requête a dépassé une limite configurée, en général un plafond de téléversement ou une limite de taille d'en-tête.
• 429 Too Many Requests : une limite de débit a été atteinte. Celui-ci mord en particulier les configurations de surveillance.

Quand un 4xx est en réalité une mauvaise configuration serveur

L'étiquette « erreur client » concerne les rôles du protocole, pas la responsabilité. La plupart des codes 4xx qui apparaissent sur un site de production par ailleurs sain sont causés par quelque chose de votre côté. Une règle de réécriture ou de routage qui ne correspond plus transforme des URL valides en 404 sur tout un répertoire, et le signe révélateur est un 404 sur beaucoup d'URL à la fois plutôt que sur une seule. Une compilation qui cesse d'émettre une ressource avec empreinte fait la même chose au niveau du fichier : chaque page demande un fichier qui renvoie 404, donc la page s'affiche mais paraît cassée.

Les couches de sécurité expliquent une bonne partie du reste. Une règle de WAF, un filtre anti-robots ou un blocage géographique peut renvoyer 403 à du trafic réel, et ceux-ci sont faciles à manquer car ils laissent généralement passer l'adresse IP du bureau. Un changement d'authentification qui laisse une page répondre 401 alors qu'elle devrait être publique est un 4xx causé entièrement par le serveur. Il en va de même pour un 400 ou un 413 provenant d'un proxy inverse dont la limite d'en-tête ou de corps est plus petite que celle de l'application, pour une requête que l'application aurait acceptée.

Comment diagnostiquer un 4xx sur votre propre site

1. Lisez d'abord le code exact et les en-têtes. Ne jugez pas sur la page d'erreur, qui peut être générique :

   curl -sS -o /dev/null -D - https://example.com/broken-page

   Cela montre la ligne de statut plus Allow, WWW-Authenticate, Retry-After et tout en-tête d'identification serveur ou CDN.
2. Déterminez si c'est une URL ou un motif récurrent. Une seule URL pointe vers un lien ou une page supprimée. Tout un préfixe de chemin pointe vers le routage, les permissions ou un déploiement.
3. Vérifiez qui a répondu. Comparez la réponse du nœud périphérique du CDN avec la réponse de l'origine. Un 403 qui n'existe qu'en périphérie est une règle de WAF ou anti-robots, pas votre application.
4. Essayez une autre identité client. Un agent utilisateur différent, une session non authentifiée ou un autre réseau peut faire passer le code de 403 à 200, ce qui localise le blocage immédiatement.
5. Lisez la ligne de journal serveur pour cette requête. Les journaux du serveur web et de l'application enregistrent quelle règle ou quel gestionnaire a produit le code. C'est l'étape qui met généralement fin à l'investigation.
6. Corrigez, puis purgez les caches. Comme plusieurs codes 4xx sont cachables, une page corrigée peut continuer à servir l'ancienne erreur depuis un cache CDN ou navigateur jusqu'à ce que l'entrée soit invalidée.

Trouver les pages 4xx que vous ne visitez jamais

Un 4xx ne met pas un serveur hors service, c'est pourquoi il passe inaperçu. Le site se charge, la page d'accueil va bien, et une section renvoie 404 ou 403 pour tout le monde sauf vous. Une vérification HTTP programmée compare le code qu'elle reçoit au code attendu, donc une page qui se met à répondre 403 au lieu de 200 déclenche une alerte plutôt que d'attendre un ticket de support. L'endroit d'où la vérification s'exécute compte aussi. HostTracker vérifie depuis plus de 300 points de contrôle répartis dans 158 villes, donc un blocage géographique ou une règle de WAF régionale apparaît comme une vraie différence entre emplacements plutôt que comme un mystère. Si le code en échec est 500, 502 ou 503 à la place, la cause est du côté serveur et le guide de la famille 5xx est le point de départ.