Comprendre les codes de réponses HTTP

Suite à une requête webservice, un code HTTP vous sera communiqué dans le but de vous informer du statut de votre requête. Si la requête est tombée en échec, il s'agira d'un code d'erreur qui pourra vous indiquer la marche à suivre dans le but de remédier à cette erreur.

Pour chaque opération, les codes de statut typiquement attendus seront renseignés au bas de l'interface. Cette liste n'est cependant pas exhaustive. Les codes pouvant être potentiellement rencontrés sont repris dans le guide pratique suivant :

Codes de réponse

  • 200 OK

Ceci est le code général de succès. Il s'agit du code le plus courant, qui indique que la requête a été traitée avec succès.

  • 201 CREATED

Ce code indique que la création s'est déroulée avec succès (via les méthodes POST ou PUT). Le champ "Location header" contiendra alors un lien vers la ressource nouvelle créée. Selon les cas, il y pourra y avoir du contenu dans le champ "Response Body" ou pas.

  • 204 NO CONTENT

Ce code indique que la requête a été traitée avec succès mais qu'il n'y a pas de contenu affiché dans le champ "Response Body". C'est typiquement le cas avec les méthodes DELETE et PUT.

  • 400 BAD REQUEST

Ceci est le code général pour indiquer que traiter la requête conduit à un résultat invalide. Cela peut par exemple être dû à des erreurs de domaine de validation, des données manquantes, ...

Il est inutile de répéter la requête sans modification de sa syntaxe, sans quoi le résultat sera le même code d'erreur.

  • 401 UNAUTHORIZED

Ce code indique que les paramètres d'authentification nécessaires pour utiliser l'API sont manquants ou invalides.

  • 403 FORBIDDEN

Ceci est le code pour quand l'utilisateur n'a pas l'autorisation d'effectuer l'opération. Il ne s'agit pas d'un problème d'authentification.

Cela peut aussi signifier que la ressource n'est pas disponible pour certaines raisons (comme des contraintes temporelles, ...)

  • 404 NOT FOUND

Ce code est utilisé quand la ressource sur laquelle est basée la requête n'a pu être trouvée.

Il peut s'agir d'un code d'erreur général, par exemple si le service veut masquer un code 401 ou 403 pour des raisons de sécurité.

  • 405 METHOD NOT ALLOWED

Ceci est le code pour indiquer que l'URL sur laquelle est basée la requête existe, mais que la méthode HTTP appelée n'est pas applicable. Par exemple, un code 405 sera obtenu si on tente d'utiliser la méthode POST quand l'API ne supporte pas la création de ce type de ressource avec ce type de méthode. Dans ce cas, le champ "Allow" indiquera les méthodes autorisées. Dans notre exemple, cela donnerait : "Allow: GET, PUT, DELETE"

  • 409 CONFLICT

Ce code indique que satisfaire à la requête créerait un conflit au niveau de la ressource. Cela peut par exemple concerner les doublons, comme essayer de créer deux profils avec les mêmes informations via un méthode PUT, ou lorsqu'on essaie de supprimer des objets racines sans que la suppression en cascade des objets enfants soit prévue.

La source du conflit sera indiquée en réponse de la requête.

  • 429 TOO MANY REQUESTS

Ce code signifie que vous avez soumis trop de requêtes simultanément ou dans un certain laps de temps.

  • 500 INTERNAL SERVER ERROR

Ceci est le message d'erreur général quand le serveur rencontre une condition inattendue qui l'empêche de satisfaire à la requête. Ce code n'est jamais renvoyé intentionnellement, mais uniquement pour les erreurs pour lesquelles vous ne pouvez pas influer de votre côté.