Code HTTP: Pas un hasard

1. Qu'est-ce qu'un code HTTP ?

Chaque réponse d'une API est accompagnée d'un code de statut qui indique au client (navigateur, front-end, mobile…) le résultat de la requête.

Il s'agit d'un nombre à 3 chiffres, par exemple 200, 404, 500.

Catégories principales

Catégorie	Intervalle	Signification
1xx	100-199	Informations (rarement utilisé en API)
2xx	200-299	Succès
3xx	300-399	Redirection
4xx	400-499	Erreur côté client
5xx	500-599	Erreur côté serveur

---

2. Les codes 2xx – Succès

Utilisés quand tout s'est bien passé.

Code	Nom	Quand l'utiliser
200 OK	Réponse standard de succès.	Exemple : GET /tickets/1 → le ticket est trouvé et renvoyé.
201 Created	Une ressource a été créée.	Exemple : POST /tickets → le ticket est créé.
204 No Content	Requête réussie mais sans corps de réponse.	Exemple : DELETE /tickets/1 → ticket supprimé.

Bonnes pratiques :

• Utiliser 201 pour une création (avec l'URL de la nouvelle ressource dans l'en-tête Location).

• Utiliser 204 si l'API n'a rien à renvoyer (exemple : suppression).

---

3. Les codes 4xx – Erreurs côté client

Ils indiquent que la requête envoyée par le client est invalide.

Code	Nom	Quand l'utiliser
400 Bad Request	La requête est mal formée ou invalide.	Exemple : le JSON envoyé est incorrect ou un champ requis est manquant.
401 Unauthorized	Authentification requise ou invalide.	Exemple : accès à /tickets sans token JWT valide.
403 Forbidden	L'utilisateur est authentifié mais n'a pas le droit d'accéder à la ressource.	Exemple : un client essaie de fermer un ticket réservé aux agents.
404 Not Found	La ressource n'existe pas.	Exemple : GET /tickets/999 alors que le ticket n'existe pas.
409 Conflict	Conflit d'état de ressource.	Exemple : tentative de ré-ouvrir un ticket déjà fermé selon le workflow.
422 Unprocessable Entity	Données valides en syntaxe mais incohérentes sur le plan métier.	Exemple : date de clôture d'un ticket avant sa date de création.

En gros :

• 401 concerne un problème d'authentification.

• 403 concerne un problème d'autorisation.

• 404 indique qu'une ressource est introuvable.

• 422 concernent les erreurs métier.

---

4. Les codes 5xx – Erreurs côté serveur

Ils signalent que le problème vient de l'API.

Code	Nom	Quand l'utiliser
500 Internal Server Error	Erreur générique côté serveur.	Exemple : exception non gérée dans le code Symfony.
502 Bad Gateway	Réponse invalide d'un serveur en amont (souvent lié à un proxy ou une gateway).	Rarement rencontré en développement local.
503 Service Unavailable	Service temporairement indisponible.	Exemple : API en maintenance ou surchargée.

Il est essentiel de gérer correctement ces erreurs pour éviter des réponses 500 génériques et offrir des messages clairs au client.

Remarque importante :

Certaines APIs renvoient parfois 200 OK même lorsqu’il y a une erreur métier, en incluant un champ error dans le JSON. Exemple :

{
  "error": "Impossible de traiter le ticket pour cet utilisateur"
}

C’est une mauvaise pratique : le code HTTP devrait refléter l’état réel de la requête. Faire passer une erreur pour un succès (200) rend l’API moins claire et oblige le client à inspecter systématiquement le contenu du JSON pour détecter les erreurs.