Codes d'état HTTP Quand retourner 404 vs 410 vs 301 (et arrêtez de deviner)

Vous avez retourné 200 avec {"error": "user not found"} dans le corps. Vos 301 sont en réalité des 302. Les ressources supprimées continuent de retourner 404 indéfiniment. Examinons les codes d'état que les développeurs utilisent le plus souvent mal, et ce qu'il faut retourner à la place.

4xx vs 5xx : Pas la même boîte

La séparation fondamentale dans les codes d'état HTTP : 4xx correspond à une faute du client, 5xx correspond à votre erreur. Simple en théorie, violée constamment en pratique.

L'offenseur le plus courant : retourner 500 pour une erreur de validation. Un utilisateur a envoyé un JSON mal formé à votre API. C'est une 400 Bad Request — son payload était erroné. Un 500 indique au client « nous avons crashé », ce qui déclenche des alertes, est enregistré comme une erreur serveur, et fait réessayer automatiquement (ce qui aggrave votre journée). Si l'utilisateur a envoyé du contenu invalide, dites-le avec un 4xx.

404 vs 410 : Le problème de la ressource supprimée

404 Not Found signifie : « Je n'ai pas cette ressource en ce moment, mais essayez plus tard. » Les robots de recherche — y compris Googlebot — considèrent 404 comme temporaire. Ils continueront à vérifier indéfiniment.

410 Gone signifie : « Cette ressource a été supprimée de manière permanente. Arrêtez de la demander. » Googlebot retire plus rapidement les URLs 410 de l'index que les URLs 404, et cesse plus tôt de les crawler. Cela compte pour l'optimisation des moteurs de recherche et pour le budget de crawling sur des grands sites.

La règle pratique : si votre API supprime définitivement une entrée et qu'elle ne revient jamais, retournez 410 sur les demandes suivantes. La seule raison de préférer 404 pour une ressource supprimée est si elle pourrait être restaurée — suppression douce avec une fenêtre de récupération, un article publié pouvant être républié, ce genre de choses. Sinon, 410 est plus honnête et les moteurs de recherche vous remercieront.

301 vs 302 (et pourquoi 307/308 existent)

301 Moved Permanently: Cette URL est disparue pour toujours, utilisez l'autre. Les navigateurs stockent les 301 de manière agressive. Les moteurs de recherche transfèrent l'équité de lien vers la destination. Si vous consolidez des domaines ou déplacez de manière permanente un site, 301 est ce que vous voulez.

302 Found: Allez sur cette autre URL pour l'instant, mais revenez plus tard sur l'ancienne. Aucun stockage. Aucun transfert d'équité de lien. Utilisez-le pour les redirections de connexion, les pages de maintenance temporaires ou les tests A/B.

Le mode de défaillance : utiliser 302 pour des déplacements permanents. Vous pensez « la même chose, juste différente », mais les moteurs de recherche ne transmettent pas l'équité de lien par 302. Des années de travail en SEO restent attachées à l'ancienne URL tandis que la nouvelle ne se classe pas. Si vous déplacez quelque chose de manière permanente, utilisez 301.

Puis il y a 307 Temporary Redirect et 308 Permanent Redirect. Ces variantes sont sécuritaires par méthode : lorsque le navigateur peut réduire une requête POST en GET lorsqu'il suit une 301/302, les 307/308 conservent la méthode originale. Si vous redirigez des points d'entrée d'API qui acceptent des corps POST, 307 (temporaire) ou 308 (permanente) conserve la méthode.

Code	Taper	Les caches ?	Conserve-t-elle la méthode ?	Utilisez pour
301	Permanent	Oui	Non (peut descendre à GET)	Les déplacements permanents d'un site, consolidation d'URLs
302	Temporaire	Non	Non (peut descendre à GET)	Redirections de connexion, indisponibilité temporaire
307	Temporaire	Non	Oui	Redirection temporaire pour des points d'entrée d'API POST
308	Permanent	Oui	Oui	Redirection permanente pour des points d'entrée d'API POST

401 vs 403 : Authentification vs Autorisation

Le nom est confus. 401 Unauthorized signifie en réalité non authentifié — vous n'êtes pas connecté, ou vos identifiants sont manquants ou invalides. 403 Forbidden signifie que vous êtes authentifié, mais que vous n'avez pas les permissions d'accéder à cette ressource.

La différence pratique : un 401 doit faire apparaître une page de connexion ou une mise à jour du token. Un 403 doit afficher un message d'interdiction d'accès. Retournez le mauvais code et votre client ne saura pas s'il doit demander des identifiants ou abandonner.

Il y a aussi une dimension de sécurité. Certains APIs retournent 404 au lieu de 403 pour des ressources que l'appelant ne peut pas accéder, afin d'éviter de révéler qu'elles existent. Si vous retournez 403 sur une ressource d'un autre tenant, vous confirmez qu'elle existe. Retourner 404 est plus sécurisé en termes d'information, bien que cela rende la déboguation plus difficile pour les utilisateurs légitimes. Choisissez le compromis qui correspond à votre modèle de menace et appliquez-le de manière cohérente.

429 : Limiter le taux, avec la tête qui aide réellement

Un simple 429 Too Many Requests est désagréable. Un 429 avec une Retry-After est vraiment utile.

HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1746374400

Retry-After peut être une durée en secondes ou une date HTTP. Les clients bien comportés feront une pause automatiquement. Sans cela, vous retournez un code d'erreur et espérez que le client comprendra quand réessayer — la plupart vont simplement frapper votre point d'entrée à nouveau, ce qui annule l'objectif de limitation du taux.

Ne retournez pas 503 pour la limitation du taux. 503 signifie « service indisponible » — l'infrastructure est en panne, une mise à jour est en cours, un interrupteur est ouvert. La limitation du taux est une décision de politique, pas une panne du service. 429 existe exactement pour cela.

L'anti-modèle « 200 avec un corps d'erreur »

Ce modèle apparaît constamment dans les API en production et doit cesser :

HTTP/1.1 200 OK
Content-Type: application/json

{"status": "error", "message": "user not found"}

Cela casse tout ce qui dépend des sémantiques HTTP. Les outils de surveillance considèrent la requête comme réussie. Les équilibres de charge la transmettent. Les bibliothèques clients ne la lancent pas. Les journaux semblent propres alors que les utilisateurs voient des erreurs. La solution est une ligne de code : retournez le bon code d'état. 200 signifie que la requête a réussi. Si elle n'a pas réussi, ne retournez pas 200.

La même logique s'applique à 201 vs 200 pour la création de ressources. Si une requête POST à /users crée un nouvel utilisateur, retournez 201 Created avec un Location en indiquant l'URL de la nouvelle ressource. Retournez 200 et vous perdez des informations que vos clients pourraient utiliser pour éviter une nouvelle requête.

Scénario API → Code d'état correct

Voici un tableau de référence pour les scénarios les plus fréquents en développement d'API REST :

Scénario	Code d'état	Remarques
Le corps de la requête est mal formé en JSON	400 Bad Request	Incluez un message pointant vers l'erreur de parsing
Champ manquant ou invalide dans la requête	422 Unprocessable Entity	Le code 422 est plus précis que 400 pour les échecs de validation sémantique
Le token d'authentification manquant ou expiré	401 Unauthorized	Inclure WWW-Authenticate en-tête
Authentifié mais sans permission	403 Forbidden	Ou 404 si le masquage de l'existence de la ressource est requis
La ressource n'est pas trouvée, peut retourner	404 Not Found	Pour une absence temporaire ou une ressource inconnue
La ressource supprimée de manière permanente	410 Gone	Les robots de recherche arrêteront plus tôt de la vérifier
Une ressource a été créée	201 Created	Ajouter Location: /resources/new-id en-tête
La suppression par DELETE a réussi, sans corps	204 No Content	Ne retournez pas un objet JSON vide avec 200
Changement permanent d'URL	301 Moved Permanently	Les moteurs de recherche transfèrent l'équité de lien
Redirection temporaire	302 Found	Aucun stockage, aucun transfert d'équité de lien
Limite de taux dépassée	429 Too Many Requests	Incluez toujours Retry-After
Exception inattendue sur le serveur	500 Internal Server Error	Ne révèle pas les traces de pile dans le corps
Une dépendance supérieure est en panne	503 Service Unavailable	Ajouter Retry-After si la panne est bornée
Redirection POST, conserve la méthode	307 ou 308	307 temporaire, 308 permanent

Quand vous êtes en pleine PR et que vous devez vérifier ce que signifie un code d'état, l'outil Recherche des codes d'état HTTP vous donne la définition du spécification, les cas d'usage typiques et la RFC qui le définit.

Vérification des chaînes de redirection

Après une migration ou une restructuration d'URL, il est utile de vérifier la chaîne complète de redirection — surtout si vous avez des 301 qui ont été ensuite mis à jour pour pointer ailleurs, créant des chaînes à plusieurs sauts qui dégradent l'équité de lien. L'outil Vérificateur de redirection trace la chaîne et montre chaque code d'état en séquence, afin de confirmer que tout se résout en un seul saut.

Vous aimerez peut-être aussi