422 Unprocessable Content

Utilisation

L’erreur 422 Unprocessable Content indique que le serveur comprend la requête mais juge le contenu sémantiquement invalide. Le type de contenu est reconnu (sinon, une erreur 415 Unsupported Media Type serait envoyée). La syntaxe est également valide (sinon, une erreur 400 Bad Request serait plus appropriée).

Une erreur de ce type survient lorsque la requête comporte, comme corps de message, un bloc d’instructions XML correctement formé et compris par le serveur, mais contenant des erreurs de logique qui entraînent une erreur côté serveur.

Remarque

Réessayer après un 422 sans modifier le corps de la requête produit la même erreur. Le client doit d’abord corriger le problème de validation. Renvoyez un 422 lorsque le Content-Type est reconnu et que la syntaxe est valide, mais que les règles métier ou la validation des champs rejettent les données.

Impact SEO

Les moteurs de recherche comme Google n’indexent pas une URL dont le statut de réponse est 422 Unprocessable Content ; par conséquent, les URL indexées par le passé qui renvoient ce code de statut HTTP sont retirées des résultats de recherche.

Exemple

Le client utilise un document XML pour demander le démarrage de la tâche n° 100. Le document XML est reconnu par le serveur et syntaxiquement correct. Le serveur n’a aucune trace d’une tâche avec id=100, la requête n’est donc pas traitable.

Requête

POST /requests HTTP/1.1
Host: example.com
Content-Type: application/xml
Content-Length: 101

<?xml version="1.0" encoding="utf-8"?>
<request>
   <id>100</id>
   <action>start</action>
</request>

Réponse

HTTP/1.1 422 Unprocessable Content
Content-Type: text/html
Content-Length: 150

<html>
  <head>
    <title>Request Failed</title>
  </head>
  <body>
   <p>Task #100 is not recognized.</p>
  </body>
</html>

Comment corriger

Inspectez d’abord le corps de la réponse. La plupart des API et des frameworks renvoient des détails d’erreur au niveau du champ, expliquant quelle valeur a échoué et pourquoi. Servez-vous de ces messages pour cerner le problème exact.

Validez le corps de la requête par rapport au schéma attendu avant l’envoi. Les déclencheurs courants sont les champs obligatoires manquants, les types de données incorrects (envoyer une chaîne là où l’API attend un nombre), les formats d’e-mail ou de date invalides, les valeurs uniques en doublon, et les valeurs d’énumération hors de l’ensemble autorisé.

Vérifiez que l’en-tête Content-Type correspond au format du corps. Envoyer du JSON avec un type de contenu text/plain provoque des échecs d’analyse sur de nombreux serveurs.

Dans Laravel, un 422 signifie généralement que les règles de validation du formulaire n’ont pas été satisfaites. Consultez l’objet errors de la réponse JSON pour connaître les noms des champs en échec et les messages de validation. Dans Rails, des validations de modèle en échec lors d’un create ou d’un update renvoient 422 par défaut. Inspectez model.errors pour les détails.

Pour les API REST comme celles de GitHub ou de Shopify, vérifiez que la charge utile de la requête correspond à la version actuelle de l’API. Les noms de champs, les paramètres obligatoires et les valeurs acceptées changent d’une version à l’autre.

Côté serveur, renvoyez des réponses d’erreur structurées énumérant chaque champ invalide, la valeur rejetée et le format attendu. Les messages génériques du type « validation failed » obligent les clients à deviner.

Références de code

.NET

HttpStatusCode.UnprocessableEntity

Rust

http::StatusCode::UNPROCESSABLE_ENTITY

Rails

:unprocessable_entity

http.StatusUnprocessableEntity

Symfony

Response::HTTP_UNPROCESSABLE_ENTITY

Python3.5+

http.HTTPStatus.UNPROCESSABLE_ENTITY

Apache HttpComponents Core

org.apache.hc.core5.http.HttpStatus.SC_UNPROCESSABLE_CONTENT
// deprecated alias: SC_UNPROCESSABLE_ENTITY

Angular

@angular/common/http/HttpStatusCode.UnprocessableEntity