Codes de statut HTTP (200 OK, 404 Not Found, etc.)

Le verdict du serveur : que signifient les codes de statut ?

Lorsqu'un client envoie une requête HTTP à un serveur, il attend une réponse. Mais au-delà du contenu (le corps) et des métadonnées (les en-têtes), la première information cruciale que le serveur renvoie est le code de statut HTTP. Ce code numérique, généralement accompagné d'un court message textuel (comme "OK" ou "Not Found"), est la manière standardisée pour le serveur d'indiquer le résultat du traitement de la requête.

Ces codes sont essentiels car ils permettent aux clients (navigateurs, applications, outils d'API, moteurs de recherche) de comprendre immédiatement si la requête a réussi, si une action supplémentaire est nécessaire (comme une redirection), ou si une erreur s'est produite (côté client ou côté serveur). Utiliser les bons codes de statut est donc fondamental pour construire des applications web et des API robustes et interopérables.

En Node.js, vous définissez le code de statut de votre réponse via l'objet `response` (`res`) avant d'envoyer les en-têtes et le corps.

Les grandes familles de codes de statut

Les codes de statut HTTP sont organisés en cinq classes, reconnaissables par leur premier chiffre :

• 1xx (Informationnel) : La requête a été reçue et le processus continue. Ces codes sont rarement utilisés ou gérés directement dans les applications web courantes. (Ex: `100 Continue`)
• 2xx (Succès) : La requête a été reçue, comprise, et traitée avec succès. C'est ce que l'on vise pour les opérations réussies. (Ex: `200 OK`, `201 Created`)
• 3xx (Redirection) : Le client doit effectuer une action supplémentaire pour compléter la requête, souvent en accédant à une autre URL. (Ex: `301 Moved Permanently`, `302 Found`)
• 4xx (Erreur Client) : La requête semble être invalide ou ne peut pas être traitée telle quelle, et l'erreur est considérée comme étant du côté du client. (Ex: `400 Bad Request`, `404 Not Found`, `403 Forbidden`)
• 5xx (Erreur Serveur) : Le serveur a rencontré une condition inattendue qui l'a empêché de traiter la requête, alors que la requête elle-même semblait valide. (Ex: `500 Internal Server Error`, `503 Service Unavailable`)

Definir le code de statut en Node.js

Vous avez deux manières principales de définir le code de statut sur l'objet `response` (`res`) :

1. Via la propriété `statusCode` : C'est la méthode la plus simple et la plus courante pour les cas simples. Vous assignez directement le numéro du code. Il faut le faire avant d'envoyer les en-têtes (avant le premier `write` ou `end`, ou avant `writeHead`).
2. Via la méthode `writeHead()` : `res.writeHead(statusCode, [statusMessage], [headers])` permet de définir le code, le message de statut optionnel, et les en-têtes en une seule fois.

Exemple :

// Méthode 1: statusCode
res.statusCode = 200;
res.setHeader('Content-Type', 'text/plain');
res.end('Tout va bien.');

// Méthode 2: writeHead
res.writeHead(404, { 'Content-Type': 'text/plain' });
res.end('Introuvable.');

Si vous ne définissez pas explicitement le `statusCode`, Node.js utilisera `200 OK` par défaut.

Les codes de statut les plus courants et leur utilisation

Classe 2xx (Succès) :

• `200 OK` : Le standard pour une requête réussie. La réponse contiendra le payload demandé (pour GET, POST) ou une confirmation (pour PUT, DELETE). C'est le code par défaut.
• `201 Created` : Indique que la requête a abouti à la création d'une nouvelle ressource (typiquement après un POST ou un PUT qui crée quelque chose). La réponse inclut souvent un en-tête `Location` pointant vers la nouvelle ressource et peut contenir une représentation de la ressource créée dans le corps.
• `204 No Content` : Indique que la requête a été traitée avec succès, mais qu'il n'y a pas de contenu à renvoyer dans le corps de la réponse (souvent utilisé pour les requêtes DELETE ou PUT qui modifient sans nécessiter de retour).

// Exemple 201 Created
if (req.method === 'POST' && req.url === '/users') {
  // ... logique pour créer un utilisateur ...
  const newUserUrl = '/users/123'; // URL de la nouvelle ressource
  res.writeHead(201, {
    'Content-Type': 'application/json',
    'Location': newUserUrl
  });
  res.end(JSON.stringify({ id: 123, message: 'Utilisateur créé' }));
}

// Exemple 204 No Content
if (req.method === 'DELETE' && req.url === '/users/123') {
  // ... logique pour supprimer l'utilisateur ...
  res.statusCode = 204;
  res.end(); // Pas de corps de réponse
}

Classe 3xx (Redirection) :

• `301 Moved Permanently` : Indique que la ressource demandée a été déplacée de façon permanente vers une nouvelle URL, spécifiée dans l'en-tête `Location`. Les clients (et moteurs de recherche) devraient utiliser la nouvelle URL à l'avenir.
• `302 Found` (ou `307 Temporary Redirect`) : Indique une redirection temporaire vers l'URL de l'en-tête `Location`. Le client doit utiliser la nouvelle URL pour cette requête, mais continuer à utiliser l'URL originale pour les requêtes futures. `307` est sémantiquement plus correct si la méthode HTTP ne doit pas changer lors de la redirection (mais `302` est très répandu).
• `304 Not Modified` : Utilisé en conjonction avec les en-têtes de mise en cache conditionnelle (comme `If-None-Match` ou `If-Modified-Since`). Indique que la ressource n'a pas changé depuis la dernière fois que le client l'a demandée, et que le client peut utiliser sa version en cache. La réponse ne doit PAS contenir de corps.

// Exemple 301 Moved Permanently
if (req.url === '/old-product-page') {
  res.writeHead(301, { 'Location': '/new-product-page' });
  res.end();
}

Classe 4xx (Erreur Client) :

• `400 Bad Request` : Erreur générique indiquant que le serveur n'a pas pu comprendre ou traiter la requête en raison d'une syntaxe invalide, d'un message malformé, ou de données manquantes/incorrectes fournies par le client.
• `401 Unauthorized` : Indique que la requête nécessite une authentification. Le client n'a pas fourni d'informations d'identification valides (ou pas du tout). Souvent accompagnée d'un en-tête `WWW-Authenticate`.
• `403 Forbidden` : Indique que le serveur a compris la requête, mais refuse de l'autoriser. Le client est authentifié (ou l'authentification n'est pas requise), mais il n'a pas les permissions nécessaires pour accéder à la ressource ou effectuer l'action.
• `404 Not Found` : Le code d'erreur le plus célèbre. Indique que le serveur n'a pas trouvé de ressource correspondant à l'URL demandée.

// Exemple 404 Not Found (cas par défaut)
// ... toutes les routes valides gérées avant ...
res.writeHead(404, { 'Content-Type': 'text/plain' });
res.end('Ressource non trouvée.');

// Exemple 400 Bad Request (validation échouée)
if (req.method === 'POST' && req.url === '/data') {
  // ... lecture du corps ...
  if (!isValid(parsedData)) { // Supposons une fonction de validation
     res.writeHead(400, { 'Content-Type': 'application/json' });
     return res.end(JSON.stringify({ error: 'Données invalides fournies.' }));
  }
  // ... traitement si valide ...
}

Classe 5xx (Erreur Serveur) :

• `500 Internal Server Error` : Un message d'erreur générique indiquant qu'une condition inattendue s'est produite côté serveur et l'a empêché de traiter la requête. C'est souvent le résultat d'un bug dans le code serveur, d'une exception non gérée, ou d'un problème de connexion à une dépendance (base de données, autre service). Il est crucial de logger les détails de l'erreur côté serveur mais de ne pas les exposer au client.
• `503 Service Unavailable` : Indique que le serveur est temporairement incapable de traiter la requête, souvent en raison d'une surcharge ou d'une maintenance. Peut être accompagné d'un en-tête `Retry-After` indiquant au client quand il pourrait réessayer.

// Exemple 500 Internal Server Error (dans un catch)
try {
  // ... code qui pourrait échouer ...
  // await database.query('...');
} catch (dbError) {
  console.error('Erreur base de données:', dbError); // Log pour le serveur
  res.writeHead(500, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({ error: 'Une erreur interne est survenue.' }));
}

Pourquoi est-ce important ?

Utiliser le code de statut HTTP approprié est fondamental pour plusieurs raisons :

• Compréhension par le client : Les navigateurs et autres clients HTTP utilisent le code de statut pour déterminer comment réagir (afficher une page, suivre une redirection, afficher un message d'erreur, utiliser le cache).
• API RESTful : Dans les API REST, les codes de statut sont un moyen standard et expressif de communiquer le résultat des opérations sur les ressources.
• Débogage : Un code d'erreur précis aide les développeurs (côté client et serveur) à identifier rapidement la nature du problème.
• SEO : Les moteurs de recherche interprètent les codes de statut. Un `301` indique un déménagement permanent (transférant le "jus" SEO), tandis qu'un `404` indique que la page n'existe pas. Des erreurs `5xx` fréquentes peuvent nuire au classement.
• Monitoring : Les outils de surveillance d'applications utilisent les codes de statut pour détecter les erreurs et évaluer la santé du service.

En conclusion, prenez le temps de choisir et d'implémenter le code de statut le plus précis pour chaque réponse de votre serveur Node.js. C'est une composante essentielle d'une communication HTTP claire, efficace et professionnelle.