Les codes font partie du contrat
Les codes HTTP indiquent comment interpreter la reponse. Ils font partie du contrat d'API.
Des codes incoherents obligent les clients a deviner et degradent le monitoring.
2xx : succes avec nuance
200 pour un succes avec corps, 201 pour une creation avec Location, 204 pour succes sans contenu.
Ces nuances aident le client a synchroniser son etat.
3xx : rarement utile
Les redirections sont rares en API. Elles peuvent etre utiles pour des endpoints deplaces, mais ajoutent de la complexite.
Si vous les utilisez, documentez-les clairement.
4xx : erreurs corrigeables
400 pour requete invalide, 401 pour auth manquante, 403 pour interdit, 404 pour ressource absente, 409 pour conflit, 422 pour validation.
L'essentiel est la coherence.
5xx : erreurs serveur
Les 5xx signalent un probleme serveur. 500 pour l'inattendu. 502/503 pour des pannes en aval.
N'utilisez pas 500 quand le client peut corriger l'erreur.
Toujours une erreur structuree
Le code ne suffit pas. Renvoyez un body structure avec un code interne et un message clair.
Cela facilite le debug et l'automatisation.
Patterns a standardiser
Creation: POST -> 201 + Location. Lecture: GET -> 200 ou 404. Update: PATCH -> 200 ou 204. Delete: DELETE -> 204 ou 404.
Ces patterns sont connus et rapides a comprendre.
Observabilite et fiabilite
Les alerts se basent sur les codes. Si les erreurs reviennent en 200, vos alertes ne voient rien.
Des codes propres renforcent la fiabilite.