- Codes HTTP : guide complet des statuts

Qu'est-ce qu'un code de statut HTTP ?

Un code de statut HTTP est un nombre à trois chiffres renvoyé par un serveur web en réponse à une requête HTTP. Défini dans la RFC 7231 (et ses successeurs de la famille RFC 9110), ce code indique au client si sa requête a été traitée avec succès, si une redirection est nécessaire, ou si une erreur s'est produite.

Chaque réponse HTTP est composée d'une ligne de statut, d'en-têtes (headers) et d'un corps optionnel. La ligne de statut suit toujours ce format :

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 42

{"id": 1, "name": "Article créé avec succès"}

Comment lire un code HTTP

Le premier chiffre définit la catégorie de réponse. Les deux suivants précisent le cas particulier. Il existe cinq familles :

Codes 1xx — Informationnel

Les codes 1xx sont des réponses provisoires. Elles indiquent que le serveur a bien reçu la requête et que le traitement se poursuit. Le client doit attendre la réponse définitive. Ces codes sont rarement visibles en production mais jouent un rôle crucial dans certains protocoles.

Codes 2xx — Succès

Les codes 2xx confirment que la requête a été traitée avec succès. C'est la famille la plus fréquemment rencontrée lors du bon fonctionnement d'une application. Choisir le bon code 2xx dans vos APIs REST est un signal fort de qualité pour les consommateurs.

Exemples de réponses pour les codes 2xx les plus courants

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "data": [
    { "id": 1, "title": "Guide HTTP", "status": "published" },
    { "id": 2, "title": "REST API", "status": "draft" }
  ],
  "total": 2
}

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Location: /api/articles/42

{
  "id": 42,
  "title": "Nouveau article",
  "createdAt": "2026-05-13T10:00:00Z"
}

HTTP/1.1 204 No Content

Codes 3xx — Redirections

Les codes 3xx indiquent que la ressource demandée a été déplacée ou nécessite une action supplémentaire. Le client doit généralement effectuer une nouvelle requête vers l'URL indiquée dans le header Location. Ces codes ont un impact direct sur le référencement naturel (SEO).

Différence entre 301 et 308, entre 302 et 307

La distinction essentielle est la préservation de la méthode HTTP :

• 301 et 302 : un POST peut être transformé en GET par le navigateur lors de la redirection (comportement historique des navigateurs).
• 307 et 308 : la méthode HTTP est strictement conservée. Un POST reste un POST après redirection.

Le code 304 — Gestion du cache HTTP

GET /api/articles HTTP/1.1
If-None-Match: "abc123etag"
If-Modified-Since: Wed, 01 Jan 2026 00:00:00 GMT


HTTP/1.1 304 Not Modified
ETag: "abc123etag"
Cache-Control: max-age=3600

Codes 4xx — Erreurs client

Les codes 4xx indiquent une erreur du côté client. La requête est mal formée, non autorisée, ou pointe vers une ressource inexistante. C'est la famille la plus riche et la plus importante à maîtriser pour concevoir des APIs claires et informatives.

Exemples de réponses JSON pour les erreurs 4xx les plus courantes

// 400 Bad Request — corps JSON mal formé ou paramètre invalide
{
  "error": "Bad Request",
  "status": 400,
  "message": "Le champ 'email' est requis.",
  "details": [
    { "field": "email", "issue": "missing" },
    { "field": "age", "issue": "must be a positive integer" }
  ]
}

// 401 Unauthorized — token manquant ou expiré
{
  "error": "Unauthorized",
  "status": 401,
  "message": "Token d'authentification manquant ou expiré.",
  "hint": "Ajoutez le header Authorization: Bearer "
}

// 403 Forbidden — authentifié mais droits insuffisants
{
  "error": "Forbidden",
  "status": 403,
  "message": "Vous n'avez pas les permissions pour effectuer cette action.",
  "requiredRole": "admin"
}

// 404 Not Found — ressource introuvable
{
  "error": "Not Found",
  "status": 404,
  "message": "L'article avec l'identifiant 99 n'existe pas.",
  "resource": "/api/articles/99"
}

// 422 Unprocessable Content — erreurs de validation métier
{
  "error": "Unprocessable Content",
  "status": 422,
  "message": "Les données soumises ne sont pas valides.",
  "errors": [
    { "field": "email", "message": "Format d'email invalide." },
    { "field": "birthdate", "message": "La date de naissance doit être dans le passé." },
    { "field": "price", "message": "Le prix ne peut pas être négatif." }
  ]
}

// 429 Too Many Requests — rate limiting atteint
{
  "error": "Too Many Requests",
  "status": 429,
  "message": "Limite de requêtes dépassée. Réessayez dans 60 secondes.",
  "retryAfter": 60,
  "limit": 100,
  "remaining": 0,
  "resetAt": "2026-05-13T10:05:00Z"
}

Codes 5xx — Erreurs serveur

Les codes 5xx indiquent que le serveur a rencontré une erreur lors du traitement d'une requête valide du client. Contrairement aux erreurs 4xx, la faute revient au serveur. Ces erreurs doivent être surveillées activement en production et ne jamais exposer de détails techniques sensibles aux clients.

Les codes 502, 503 et 504 en détail

Ces trois codes sont fréquemment confondus en environnement avec proxy inverse (Nginx, HAProxy, Cloudflare) :

• 502 Bad Gateway : l'application en amont (PHP-FPM, Node.js, container) a renvoyé une réponse invalide ou s'est plantée.
• 503 Service Unavailable : l'application est volontairement indisponible (déploiement, maintenance) ou surchargée.
• 504 Gateway Timeout : l'application a mis trop de temps à répondre — le proxy a coupé la connexion avant la fin du traitement.

HTTP/1.1 503 Service Unavailable
Content-Type: application/json; charset=utf-8
Retry-After: 3600

{
  "error": "Service Unavailable",
  "status": 503,
  "message": "Maintenance planifiée en cours. Service disponible dans environ 1 heure.",
  "retryAfter": 3600
}

Bonnes pratiques API REST

Utiliser les bons codes HTTP dans une API REST n'est pas optionnel — c'est un contrat implicite avec les consommateurs de votre API. Un code 200 sur une erreur, ou un 500 pour un problème de validation, crée de la confusion et rend le débogage difficile.

Tableau CRUD — quel code HTTP retourner

Structure de réponse JSON standardisée

Adoptez une structure cohérente pour toutes vos réponses, succès comme erreurs :

// Structure de réponse succès avec pagination
{
  "status": "success",
  "data": [
    { "id": 1, "title": "Guide HTTP complet", "category": "html" },
    { "id": 2, "title": "REST API Design", "category": "back" }
  ],
  "meta": {
    "total": 142,
    "page": 1,
    "perPage": 20,
    "lastPage": 8
  }
}

// Structure de réponse erreur — format RFC 7807 (Problem Details)
{
  "type": "https://api.example.com/problems/validation-error",
  "title": "Erreur de validation",
  "status": 422,
  "detail": "Les données soumises contiennent des erreurs.",
  "instance": "/api/articles",
  "errors": [
    {
      "field": "title",
      "message": "Le titre est requis et doit contenir entre 10 et 60 caractères."
    },
    {
      "field": "category",
      "message": "La catégorie 'unknown' n'est pas valide. Valeurs acceptées : html, css, js."
    }
  ]
}

• Utiliser 201 (pas 200) pour la création d'une ressource via POST
• Retourner 204 No Content pour une suppression réussie — sans corps de réponse
• Distinguer 400 (syntaxe invalide) de 422 (règle métier violée)
• Distinguer 401 (non authentifié) de 403 (authentifié mais non autorisé)
• Utiliser 409 Conflict pour les doublons ou conflits d'état (pas 422)
• Inclure Retry-After dans les réponses 429 et 503
• Inclure Location dans les réponses 201 et 301/302
• Ne jamais retourner 200 OK avec un corps contenant une erreur ("success: false")
• Adopter le format RFC 7807 (Problem Details) pour les réponses d'erreur
• Logger les 4xx (pour détecter les bugs clients) et les 5xx (pour détecter les bugs serveur)

Conclusion

Les codes de statut HTTP sont le langage universel du web. Maîtriser les cinq familles — 1xx informationnel, 2xx succès, 3xx redirection, 4xx erreur client, 5xx erreur serveur — est indispensable pour concevoir des APIs cohérentes, debugger efficacement et optimiser le référencement de vos sites.

La prochaine fois que vous concevez un endpoint d'API, posez-vous toujours ces deux questions : "Quelle est la sémantique exacte de cette opération ?" et "Quel code HTTP exprime le mieux ce résultat ?". Un bon choix de code HTTP réduit la documentation nécessaire et accélère l'intégration pour les développeurs qui consomment votre API.