Codes de statut HTTP : Ce qu'ils signifient et quand les utiliser
Au-delà de 200 et 404. Un guide pratique des codes de statut pour les développeurs d'API.
Ton API retourne 200. Le corps de la réponse dit {"error": "Not found"}.
C'est faux. Les codes de statut existent pour une raison. Utilise-les correctement.
Les cinq catégories
1xx — Informationnel. Rarement vu en pratique.
2xx — Succès. La requête a fonctionné.
3xx — Redirection. Va ailleurs.
4xx — Erreur client. Tu as fait quelque chose de mal.
5xx — Erreur serveur. On a fait quelque chose de mal.
Les codes que tu vas vraiment utiliser
Succès (2xx)
200 OK — Succès standard. Utilise pour les requêtes GET qui retournent des données.
201 Created — La ressource a été créée. Utilise après un POST réussi qui crée quelque chose.
204 No Content — Succès, mais rien à retourner. Utilise pour DELETE ou mises à jour qui ne retournent pas de données.
Erreurs client (4xx)
400 Bad Request — Requête mal formée. JSON invalide, champs requis manquants, mauvais types de données.
401 Unauthorized — Pas d'authentification. L'utilisateur doit se connecter.
403 Forbidden — Authentifié mais pas autorisé. L'utilisateur existe mais manque de permission.
404 Not Found — La ressource n'existe pas. Le classique.
409 Conflict — La requête entre en conflit avec l'état actuel. Nom d'utilisateur en double, incompatibilité de version.
422 Unprocessable Entity — Syntaxiquement correct mais sémantiquement faux. JSON valide mais règles métier violées.
429 Too Many Requests — Limitation de débit. Ralentis.
Erreurs serveur (5xx)
500 Internal Server Error — Échec serveur générique. Quelque chose a planté.
502 Bad Gateway — Le serveur en amont a échoué. Ton serveur va bien, mais quelque chose dont il dépend ne va pas.
503 Service Unavailable — Temporairement hors service. Maintenance ou surcharge.
504 Gateway Timeout — Le serveur en amont n'a pas répondu à temps.
Erreurs courantes
200 avec erreur dans le corps. Si c'est une erreur, utilise un code de statut d'erreur. Ne force pas les clients à analyser le corps pour savoir si ça a réussi.
500 pour les erreurs de validation. L'utilisateur a soumis de mauvaises données ? C'est 400 ou 422, pas 500. Le serveur n'est pas cassé—la requête l'est.
Confusion 401 vs 403. 401 signifie "qui es-tu ?" 403 signifie "je sais qui tu es, mais non."
404 pour tout. "Non trouvé" n'est pas toujours la bonne réponse. Mauvaise méthode ? 405. Limite de débit ? 429.
Concevoir des APIs
Sois spécifique. Les clients peuvent gérer les erreurs spécifiques intelligemment. Les erreurs génériques signifient gestion générique.
Inclus les détails d'erreur dans le corps :
{
"error": "validation_failed",
"message": "Email format is invalid",
"field": "email"
}
Le code de statut dit quelle catégorie de problème. Le corps explique spécifiquement.
Gérer les codes de statut en tant que client
2xx — Analyse la réponse, procède normalement.
4xx — Ta faute. Log, affiche à l'utilisateur, corrige la requête.
5xx — Faute du serveur. Peut-être réessayer avec backoff. Peut-être alerter.
3xx — Suis les redirections automatiquement (la plupart des clients HTTP le font).
Ne vérifie pas juste 200. Vérifie le succès (2xx) et gère les autres cas de manière appropriée.
Les codes de statut sont de la communication. Utilise-les correctement et les APIs deviennent auto-documentées. Utilise-les mal et le débogage devient du devinement.