Blog

Quels Codes de Statut HTTP Utiliser pour les APIs REST ?

Ashley Innocent

Ashley Innocent

13 March 2026

Quels Codes de Statut HTTP Utiliser pour les APIs REST ?

Apidog pour les entreprises

Déploiement sur site

SSO & RBAC

Conforme SOC 2

Découvrir Apidog Enterprise

TL;DR

Les API REST doivent utiliser correctement les codes de statut HTTP : 200 pour un GET réussi, 201 pour un POST réussi avec création de ressource, 204 pour un DELETE réussi, 400 pour les erreurs client, 401 pour les échecs d'authentification, 404 pour les ressources introuvables et 500 pour les erreurs serveur. La Modern PetstoreAPI implémente tous les codes de statut HTTP standard avec la sémantique appropriée et des réponses d'erreur RFC 9457.

Introduction

Votre API renvoie 200 OK pour tout. Succès ? 200 OK. Erreur de validation ? 200 OK avec un message d'erreur dans le corps. Ressource introuvable ? 200 OK avec {"error": "not found"}. Échec d'authentification ? Vous l'avez deviné — 200 OK.

C'est faux. Les codes de statut HTTP existent pour une raison. Ils indiquent aux clients ce qui s'est passé sans analyser le corps de la réponse. Les caches, les proxys et les outils de surveillance s'appuient sur les codes de statut. Lorsque vous renvoyez 200 pour des erreurs, vous brisez tout l'écosystème HTTP.

L'ancienne Swagger Petstore commettait des erreurs de codes de statut : renvoyer 200 pour les requêtes POST qui devraient renvoyer 201, utiliser 200 pour les opérations DELETE qui devraient renvoyer 204, et manquer des codes d'erreur importants. Modern PetstoreAPI corrige cela en implémentant une sémantique HTTP appropriée sur tous les points de terminaison.

💡
Si vous développez ou testez des API REST, Apidog vous aide à valider l'utilisation des codes de statut, à tester les scénarios d'erreur et à garantir que votre API respecte les standards HTTP. Vous pouvez définir les codes de statut attendus, exécuter des tests automatisés et détecter les réponses incorrectes avant le déploiement.
télécharger l'application

Dans ce guide, vous apprendrez quels codes de statut HTTP sont importants pour les API REST, quand utiliser chacun d'eux, et comment Modern PetstoreAPI les implémente correctement.

Le problème des codes de statut

Beaucoup d'API traitent les codes de statut comme une réflexion après coup. Le résultat : une sémantique HTTP brisée et des clients confus.

L'anti-pattern "200 OK pour tout"

// Succès
GET /users/123
200 OK
{"id": 123, "name": "John"}

// Erreur (mais toujours 200 !)
GET /users/999
200 OK
{"error": "User not found"}

// Erreur de validation (toujours 200 !)
POST /users
200 OK
{"error": "Email is required"}

Problèmes :

Pourquoi cela se produit

Les développeurs renvoient 200 parce que :

  1. Ils ne connaissent pas les autres codes de statut
  2. Ils pensent que les codes de statut sont facultatifs
  3. Ils veulent éviter de "casser" les clients
  4. Ils copient de mauvais exemples (comme l'ancienne Swagger Petstore)

Codes de statut HTTP essentiels pour les API REST

Vous n'avez pas besoin de tous les plus de 60 codes de statut HTTP. Concentrez-vous sur ces codes essentiels.

Référence rapide

Succès (2xx) :

Erreurs client (4xx) :

Erreurs serveur (5xx) :

Codes de succès (2xx)

Les codes de succès indiquent que la requête a réussi. Différents codes véhiculent différentes significations.

200 OK

À utiliser pour : Les requêtes GET, PUT, PATCH réussies qui renvoient des données.

GET /pets/123
200 OK
{
  "id": "019b4132-70aa-764f-b315-e2803d882a24",
  "name": "Fluffy",
  "species": "CAT"
}

Ne pas utiliser pour : Les requêtes POST qui créent des ressources (utiliser 201), les requêtes DELETE (utiliser 204).

201 Created

À utiliser pour : Les requêtes POST réussies qui créent une nouvelle ressource.

POST /pets
201 Created
Location: https://petstoreapi.com/pets/019b4132-70aa-764f-b315-e2803d882a24
{
  "id": "019b4132-70aa-764f-b315-e2803d882a24",
  "name": "Fluffy",
  "species": "CAT"
}

Points clés :

Modern PetstoreAPI renvoie 201 pour toutes les opérations POST qui créent des ressources.

204 No Content

À utiliser pour : Les requêtes DELETE, PUT ou PATCH réussies sans corps de réponse.

DELETE /pets/019b4132-70aa-764f-b315-e2803d882a24
204 No Content

Points clés :

Codes d'erreur client (4xx)

Les codes d'erreur client indiquent que le client a commis une erreur. La requête ne doit pas être réessayée sans modification.

400 Bad Request

À utiliser pour : Requêtes malformées, JSON invalide, champs obligatoires manquants.

POST /pets
400 Bad Request
Content-Type: application/problem+json

{
  "type": "https://petstoreapi.com/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Request validation failed",
  "invalid-params": [
    {
      "name": "name",
      "reason": "Name is required"
    }
  ]
}

Modern PetstoreAPI utilise le format RFC 9457 pour toutes les réponses d'erreur.

401 Unauthorized

À utiliser pour : Identifiants d'authentification manquants ou invalides.

GET /pets
401 Unauthorized
WWW-Authenticate: Bearer realm="PetstoreAPI"

{
  "type": "https://petstoreapi.com/errors/authentication-required",
  "title": "Authentication Required",
  "status": 401,
  "detail": "Valid authentication credentials required"
}

Points clés :

403 Forbidden

À utiliser pour : Utilisateur authentifié mais manquant de permission.

DELETE /pets/019b4132-70aa-764f-b315-e2803d882a24
403 Forbidden

{
  "type": "https://petstoreapi.com/errors/insufficient-permissions",
  "title": "Insufficient Permissions",
  "status": 403,
  "detail": "Vous n'avez pas la permission de supprimer cet animal"
}

Différence avec 401 :

404 Not Found

À utiliser pour : La ressource n'existe pas.

GET /pets/nonexistent-id
404 Not Found

{
  "type": "https://petstoreapi.com/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Animal non trouvé"
}

Ne pas utiliser pour : Les échecs d'autorisation (utiliser 403), les erreurs de validation (utiliser 400).

409 Conflict

À utiliser pour : Conflits de ressources comme des doublons ou des non-concordances de version.

POST /pets
409 Conflict

{
  "type": "https://petstoreapi.com/errors/duplicate-resource",
  "title": "Duplicate Resource",
  "status": 409,
  "detail": "Un animal avec cet ID de puce électronique existe déjà"
}

422 Unprocessable Entity

À utiliser pour : Format de requête valide mais erreurs sémantiques.

POST /pets
422 Unprocessable Entity

{
  "type": "https://petstoreapi.com/errors/business-rule-violation",
  "title": "Business Rule Violation",
  "status": 422,
  "detail": "Impossible d'adopter plus de 5 animaux par foyer"
}

Différence avec 400 :

429 Too Many Requests

À utiliser pour : Limite de requêtes dépassée.

GET /pets
429 Too Many Requests
RateLimit-Limit: 100
RateLimit-Remaining: 0
RateLimit-Reset: 1678886400

{
  "type": "https://petstoreapi.com/errors/rate-limit-exceeded",
  "title": "Rate Limit Exceeded",
  "status": 429,
  "detail": "Limite de requêtes de 100 requêtes par heure dépassée"
}

Modern PetstoreAPI utilise les en-têtes de limite de débit IETF.

Codes d'erreur serveur (5xx)

Les codes d'erreur serveur indiquent que le serveur a échoué. Les clients peuvent réessayer ces requêtes.

500 Internal Server Error

À utiliser pour : Erreurs serveur inattendues.

GET /pets
500 Internal Server Error

{
  "type": "https://petstoreapi.com/errors/internal-error",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "Une erreur inattendue est survenue"
}

Ne pas inclure : Les traces de pile, les détails internes, les erreurs de base de données en production.

503 Service Unavailable

À utiliser pour : Indisponibilité temporaire (maintenance, surcharge).

GET /pets
503 Service Unavailable
Retry-After: 3600

{
  "type": "https://petstoreapi.com/errors/service-unavailable",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "Service temporairement indisponible pour maintenance"
}

Inclure l'en-tête Retry-After pour indiquer aux clients quand réessayer.

Comment Modern PetstoreAPI utilise les codes de statut

Modern PetstoreAPI implémente une sémantique HTTP appropriée sur tous les points de terminaison.

Exemple : Gestion des animaux

// Lister les animaux
GET /pets
200 OK

// Créer un animal
POST /pets
201 Created
Location: https://petstoreapi.com/pets/{id}

// Obtenir un animal
GET /pets/{id}
200 OK (trouvé) ou 404 Not Found

// Mettre à jour un animal
PUT /pets/{id}
200 OK (avec corps) ou 204 No Content

// Supprimer un animal
DELETE /pets/{id}
204 No Content (succès) ou 404 Not Found

Réponses d'erreur

Toutes les erreurs utilisent le format RFC 9457 :

{
  "type": "https://petstoreapi.com/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "La validation de la requête a échoué",
  "instance": "/pets",
  "invalid-params": [
    {
      "name": "name",
      "reason": "Le nom doit contenir entre 1 et 100 caractères"
    }
  ]
}

Consultez la documentation de gestion des erreurs de Modern PetstoreAPI pour des exemples complets.

Tester les codes de statut avec Apidog

Apidog vous aide à tester le comportement des codes de statut dans tous les scénarios.

Définir les codes de statut attendus

paths:
  /pets:
    post:
      responses:
        '201':
          description: Animal créé
        '400':
          description: Erreur de validation
        '401':
          description: Authentification requise
        '429':
          description: Limite de requêtes dépassée

Tester tous les scénarios

Créez des cas de test pour :

Tests automatisés

// Script de test Apidog
pm.test("Renvoie 201 pour une création réussie", () => {
  pm.response.to.have.status(201);
  pm.response.to.have.header("Location");
});

pm.test("Renvoie 400 pour les champs obligatoires manquants", () => {
  pm.response.to.have.status(400);
  pm.expect(pm.response.json().type).to.include("validation-error");
});

Erreurs courantes à éviter

Erreur 1 : Utiliser 200 pour POST

// Incorrect
POST /pets
200 OK

// Correct
POST /pets
201 Created
Location: https://petstoreapi.com/pets/{id}

Erreur 2 : Utiliser 200 pour DELETE

// Incorrect
DELETE /pets/{id}
200 OK
{"message": "Supprimé avec succès"}

// Correct
DELETE /pets/{id}
204 No Content

Erreur 3 : Confondre 401 et 403

// Incorrect : L'utilisateur est authentifié mais n'a pas la permission
401 Unauthorized

// Correct
403 Forbidden

Erreur 4 : Utiliser 500 pour les erreurs client

// Incorrect : L'erreur de validation renvoie 500
POST /pets
500 Internal Server Error

// Correct
POST /pets
400 Bad Request

Conclusion

Les codes de statut HTTP ne sont pas facultatifs. Ils font partie de la spécification HTTP et sont essentiels pour construire des API REST appropriées.

Utilisez les codes de statut corrects :

Modern PetstoreAPI démontre l'utilisation correcte des codes de statut sur tous les points de terminaison. Étudiez la documentation de l'API REST pour voir une implémentation correcte.

Testez vos codes de statut avec Apidog pour vous assurer que votre API respecte les standards HTTP.

FAQ

Dois-je utiliser 200 ou 204 pour un DELETE réussi ?

Utilisez 204 No Content. Cela indique un succès sans corps de réponse, ce qui économise de la bande passante. Utilisez 200 uniquement si vous devez renvoyer des informations sur la ressource supprimée.

Quelle est la différence entre 400 et 422 ?

400 signifie que la requête est malformée (JSON invalide, types incorrects). 422 signifie que la requête est bien formée mais viole les règles métier.

Quand dois-je utiliser 401 vs 403 ?

401 signifie "authentifiez-vous" (identifiants manquants ou invalides). 403 signifie "vous êtes authentifié mais non autorisé" (permissions insuffisantes).

Dois-je renvoyer 404 ou 403 pour les ressources auxquelles les utilisateurs ne peuvent pas accéder ?

Renvoyez 403 si la ressource existe mais que l'utilisateur n'a pas la permission. Renvoyez 404 si vous voulez masquer l'existence de la ressource aux utilisateurs non autorisés.

Comment tester tous les scénarios de codes de statut ?

Utilisez Apidog pour créer des cas de test pour les succès, les erreurs de validation, les échecs d'authentification, les ressources introuvables et les erreurs serveur. Exécutez des tests automatisés en CI/CD.

Quel code de statut pour la limitation de débit ?

Utilisez 429 Too Many Requests avec les en-têtes RateLimit-*. Incluez Retry-After pour indiquer aux clients quand ils peuvent réessayer.

Dois-je utiliser 500 pour toutes les erreurs serveur ?

Utilisez 500 pour les erreurs inattendues. Utilisez 502 pour les défaillances de services en amont, 503 pour l'indisponibilité temporaire et 504 pour les délais d'attente.

Comment Modern PetstoreAPI gère-t-elle les erreurs ?

Toutes les erreurs utilisent le format RFC 9457 avec les codes de statut appropriés. Consultez la documentation sur la gestion des erreurs pour des exemples.

Pratiquez le Design-first d'API dans Apidog

Découvrez une manière plus simple de créer et utiliser des API

S'inscrire gratuitementTélécharger