Codes de statut HTTP

Les chiffres qui disent tout sans un mot

Rôle des codes de statut

Trois chiffres. C'est tout.
Pas de phrases, pas d'explications — juste un code qui résume l'issue de la requête.
Le client les comprend, s'y adapte, agit en conséquence.
Dans l'ombre des réseaux, c'est le langage des résultats. Brut, universel, sans appel.

Grandes catégories

Le premier chiffre définit la classe. La famille de la réponse.

1xx : information

Rare dans les APIs.
100 Continue — « Continue, j'écoute. »
101 Switching Protocols — « On change de protocole. »
Transitoire, technique.
Souvent invisible, gérée en interne par le navigateur ou le client.

2xx : succès

Tout s'est bien passé. La transaction est valide.

• 200 OK — La réponse standard. Requête traitée, voici les données.
• 201 Created — Une ressource a été créée. Souvent renvoyé après un POST avec un header Location pointant vers la nouvelle URI.
• 204 No Content — Succès, mais rien à renvoyer. Après un DELETE réussi, ou un PUT qui ne nécessite pas de retour.
  Le client peut avancer. La voie est libre.

3xx : redirection

La ressource n'est plus là où on pensait.

• 301 Moved Permanently — L'URI a changé pour toujours. Mémorise la nouvelle.
• 304 Not Modified — Rien n'a changé depuis la dernière fois. Utilisé avec le cache.
• 308 Permanent Redirect — Comme le 301, mais garde la même méthode HTTP.
  Le client doit suivre. La cible a bougé.

4xx : erreur client

La requête est mal formée, interdite, impossible. La faute est du côté appelant.

• 400 Bad Request — La syntaxe de la requête est invalide.
• 401 Unauthorized — Authentification nécessaire. Qui es-tu ?
• 403 Forbidden — Authentifié mais pas autorisé. Tu n'as pas les droits.
• 404 Not Found — La ressource n'existe pas à cette URI.
• 409 Conflict — Conflit avec l'état actuel (ex: mise à jour simultanée).
  Le client doit se reprendre. Corriger son tir.

5xx : erreur serveur

Le serveur a échoué. C'est de son côté que ça a coincé.

• 500 Internal Server Error — Erreur générique, imprévue.
• 502 Bad Gateway — Un proxy ou un service en amont a lâché.
• 503 Service Unavailable — Service temporairement indisponible (maintenance, surcharge).
• 504 Gateway Timeout — Timeout entre deux services.
  Le client peut retenter plus tard. La panne n'est pas de son fait.

Importance de leur bon usage dans une API REST

Choisir le bon code, c'est respecter le contrat.

• Une création réussie → 201 Created, pas 200 OK.
• Une suppression sans retour → 204 No Content.
• Une ressource introuvable → 404, pas un 200 avec un message d'erreur dans le corps.
• Un conflit de version → 409 Conflict.
• Trop de requêtes → 429 Too Many Requests.

Une API propre utilise les codes comme prévu.
Pas de 200 pour une erreur, pas de 500 pour une faute client.
Chaque code guide le client, automatise les retours, simplifie la logique.
Coder correctement, c’offrir une API lisible, fiable, prévisible.
Même dans l’ombre, les chiffres ne mentent pas.