Les codes de statut Le code de statut est la première chose qu'un client regarde. Un bon code évite au client de devoir lire le body pour savoir si ça a marché. Une API qui répond toujours 200 OK avec {"error": true} dans le body oblige chaque client à réinventer la gestion d'erreurs. Le code de statut est fait pour ça : utilisez-le. Les exemples ci-dessous concernent l'API d'une bibliothèque en ligne : des livres, des membres, des emprunts. 2xx - Succès Code Quand l'utiliser Exemple 200 OK Succès avec un body GET /v1/livres 201 Created Ressource créée. Ajouter le header Location POST /v1/emprunts 204 No Content Succès sans body DELETE /v1/emprunts/42 3xx - Redirection Code Quand l'utiliser 301 Moved Permanently La ressource a changé d'adresse définitivement 304 Not Modified La version en cache du client est toujours bonne 4xx - Erreur du client Code Quand l'utiliser Exemple 400 Bad Request Requête mal formée Un body qui n'est pas du JSON valide 401 Unauthorized Pas authentifié, ou authentification invalide GET /v1/me sans token 403 Forbidden Authentifié, mais pas autorisé Un membre qui veut supprimer un livre du catalogue 404 Not Found La ressource n'existe pas GET /v1/livres/999999 405 Method Not Allowed Méthode non supportée sur cette URI. Ajouter le header Allow DELETE /v1/livres (supprimer tout le catalogue) 406 Not Acceptable Format demandé dans Accept indisponible Accept: image/png 409 Conflict Conflit avec l'état actuel de la ressource Emprunter un livre déjà emprunté 418 I'm a teapot Le serveur est une théière (RFC 2324, poisson d'avril de 1998) Demander un café à une théière 422 Unprocessable Content Requête bien formée mais données invalides Une date de retour antérieure à la date d'emprunt 429 Too Many Requests Trop de requêtes. Ajouter le header Retry-After Un script qui interroge l'API en boucle 5xx - Erreur du serveur Code Quand l'utiliser 500 Internal Server Error Bug côté serveur. Ne jamais le renvoyer volontairement 502 Bad Gateway Un intermédiaire n'a pas obtenu de réponse valide du serveur 503 Service Unavailable Serveur indisponible (maintenance, surcharge) Les pièges classiques 401 ou 403 ? 401 : « je ne sais pas qui tu es ». 403 : « je sais qui tu es, et c'est non ». 400 ou 422 ? 400 : je n'arrive pas à lire ta requête. 422 : je l'ai lue, mais son contenu n'est pas valide. FastAPI renvoie 422 par défaut pour les erreurs de validation. 404 ou 403 ? Pour une ressource qui appartient à quelqu'un d'autre, répondre 404 évite de révéler qu'elle existe. On en reparle au chapitre 8. La liste complète est sur MDN . Et pour les retenir : http.cat .