422 Unprocessable Entity : ce que ça signifie et comment le corriger

Ce que signifie 422 Unprocessable Entity

422 a son origine dans WebDAV (RFC 4918) et a ensuite été largement adopté par les API REST comme réponse standard pour les échecs de validation sémantique. La RFC 9110 a formellement renommé le texte de statut en 422 Unprocessable Content, abandonnant le libellé « Entity » spécifique à WebDAV, bien que les deux noms décrivent le code de statut identique et que « Unprocessable Entity » reste le libellé de loin le plus courant dans les valeurs par défaut des frameworks et la documentation des API. La distinction qui compte est syntaxe contre sémantique : le JSON s'est analysé correctement, chaque type de champ requis correspond, et la requête est bien formée selon chaque règle structurelle, mais une valeur qu'elle contient enfreint une règle métier, comme une adresse e-mail au mauvais format, une date dans le passé là où une date future est requise, ou un champ qui référence un enregistrement qui n'existe pas.

Comment l'erreur apparaît

Un 422 apparaît presque jamais comme une erreur de navigation de navigateur, puisque c'est très majoritairement une réponse d'API plutôt que quelque chose qu'un lien ou une soumission de formulaire déclenche directement ; cela apparaît dans un onglet réseau, une notification d'erreur, ou une assertion de test échouée. Depuis la ligne de commande, le corps de la réponse est l'endroit où se trouve le détail utile :

curl -i -X POST https://api.example.com/v1/users   -H "Content-Type: application/json"   -d '{"email": "not-an-email", "age": -5}'

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{"errors": {"email": ["is not a valid email"], "age": ["must be greater than 0"]}}

La plupart des API bien construites renvoient un corps d'erreur structuré aux côtés du 422, nommant exactement quel champ a échoué et pourquoi, plutôt que de laisser l'appelant deviner à partir du seul code de statut.

Ce qui provoque un 422 Unprocessable Entity

• Des erreurs de validation dans les API REST. Les applications Rails renvoient couramment 422 automatiquement quand un modèle ActiveRecord échoue à la validation lors de la création ou de la mise à jour. La validation de requête de formulaire de Laravel renvoie 422 par défaut pour les règles échouées. FastAPI, construit sur Pydantic, renvoie 422 chaque fois que les données de la requête échouent aux vérifications de type ou de contrainte d'un modèle Pydantic, ce qui explique pourquoi c'est l'un des codes de statut les plus fréquemment vus dans les projets FastAPI en particulier.
• Un champ du bon type mais avec une valeur invalide. Une chaîne là où une chaîne était attendue, mais une qui échoue à une vérification de format, une limite de longueur, ou une liste de valeurs autorisées.
• Une référence vers quelque chose qui n'existe pas. Une clé étrangère, un id utilisateur, ou un slug dans le corps de la requête qui est syntaxiquement correct mais ne correspond à aucun enregistrement réel.
• Des règles métier au-delà de la simple validation de champ. Un code de réduction syntaxiquement valide mais expiré, ou une quantité qui est un entier valide mais dépasse le stock disponible.
• Un champ requis entièrement manquant. Selon le framework, un champ requis absent peut renvoyer 422 plutôt que 400, puisque la requête s'analyse bien, il lui manque simplement une valeur que la couche de validation exige.

422 face à 400

La ligne de démarcation est syntaxe contre sémantique. 400 Bad Request signifie que le serveur n'a pas pu analyser la requête du tout, par exemple du JSON mal formé ou un corps qui n'est valide selon aucune règle structurelle. 422 signifie que la requête s'est analysée sans aucun problème, et que chaque champ est du bon type, mais qu'une valeur qu'elle contient échoue à une règle que l'application vérifie après l'analyse. En pratique, de nombreuses API brouillent cette distinction et utilisent 400 pour les deux cas, ce qui se défend mais est moins précis ; un client s'intégrant à une API devrait lire le corps de la réponse plutôt que de se fier au seul code de statut pour savoir exactement ce qui a échoué.

Comment corriger une erreur 422

Si vous êtes un client appelant une API

1. Lisez le corps de la réponse, pas seulement le code de statut. La réponse 422 d'une API bien construite nomme le champ et la règle précis qui ont échoué, ce qui vous dit exactement quoi corriger sans deviner davantage.
2. Vérifiez le champ par rapport aux contraintes documentées de l'API comme le format, la longueur, et les valeurs autorisées, puisque ce sont des règles métier que le seul schéma ne vous montrera pas.
3. Traitez le 422 comme un signal de corriger les données, pas de réessayer la requête inchangée. Réessayer une requête non modifiée qui a échoué à la validation échouera identiquement à chaque fois ; un client bien conçu devrait présenter l'erreur précise à l'utilisateur plutôt que de réessayer silencieusement.

Si vous gérez l'API

1. Renvoyez toujours un corps d'erreur structuré aux côtés du 422, nommant le champ et la règle qui ont échoué, plutôt qu'un simple code de statut sans explication.
2. Gardez les messages d'erreur de validation précis et actionnables, par exemple « email must be a valid address » plutôt qu'un générique « validation failed » qui force l'appelant à deviner lequel parmi plusieurs champs posait problème.
3. Décidez délibérément entre 400 et 422 pour votre API et documentez le choix, pour que les intégrateurs puissent construire une gestion d'erreur fiable au lieu de traiter chaque 4xx de la même façon.
4. Journalisez les charges utiles validées-mais-rejetées pendant le développement pour détecter les cas où votre propre code client envoie des données qui échouent systématiquement à la validation, ce qui pointe souvent vers une incompatibilité entre le client et les règles réelles de l'API.

Comment un client devrait gérer une réponse 422

Un client bien conçu traite le 422 comme fondamentalement différent d'une erreur 5xx ou d'un échec réseau : cela signifie que le serveur est sain et fonctionne correctement, et que l'appelant a envoyé quelque chose que le serveur n'acceptera jamais tel quel. La bonne réponse est d'analyser le corps d'erreur, de faire correspondre chaque champ en échec avec le formulaire ou l'entrée qui l'a produit, et de montrer à l'utilisateur quelque chose d'actionnable, pas de réessayer avec un backoff comme vous le feriez pour un délai dépassé ou un 503. Les tests automatisés qui exercent la couche de validation d'une API devraient faire une assertion sur le corps d'erreur précis renvoyé, pas seulement sur le code de statut 422, puisque c'est cela qui confirme que la logique de validation elle-même est correcte.

Comment prévenir que des 422 ne passent inaperçus

Une règle de validation qui a changé de façon inattendue, que ce soit à cause d'un déploiement, d'une mise à jour de bibliothèque tierce, ou d'une migration de schéma, peut se mettre tranquillement à rejeter des requêtes qui réussissaient auparavant. Une vérification HTTP qui soumet une charge utile connue pour être valide et fait une assertion sur le code de statut attendu détecte ce type de régression immédiatement après un déploiement. Pour les API avec plus d'un point de terminaison ou une charge utile que le seul code de statut ne peut pas entièrement vérifier, une surveillance d'API qui vérifie aussi le corps de la réponse confirme la logique de validation elle-même, pas seulement que le serveur est joignable.

Erreurs associées

Voir 400 Bad Request pour le cas de requête-qui-n'a-pas-pu-s'analyser auquel ce guide s'oppose, l'aperçu des 4xx pour la famille plus large, et 401 Unauthorized et 405 Method Not Allowed ailleurs dans ce lot.

Questions fréquentes

422 Unprocessable Entity est-il la même chose que 422 Unprocessable Content ?

Oui. La RFC 9110 a renommé la phrase de raison en Unprocessable Content, mais c'est le même code de statut avec la même signification ; la plupart des frameworks et documentations d'API utilisent encore l'ancien libellé Unprocessable Entity.

Pourquoi mon application FastAPI renvoie-t-elle 422 pour un champ manquant ?

FastAPI valide automatiquement les données de la requête par rapport à vos modèles Pydantic, et un champ requis manquant, ou un du mauvais type, échoue à cette validation et renvoie 422 avec un corps décrivant exactement quel champ et quelle règle ont échoué.

Devrais-je réessayer une requête qui a reçu un 422 ?

Seulement après avoir changé les données qui ont échoué à la validation. Réessayer la requête identique produira le 422 identique à chaque fois, puisque le serveur rejette correctement et systématiquement la même entrée invalide.

Quelle est la différence entre 422 et 400 en pratique ?

400 est pour une requête que le serveur ne peut pas analyser du tout. 422 est pour une requête qui s'analyse bien mais contient une valeur qui échoue à une règle de validation ou métier. De nombreuses API réelles utilisent 400 pour les deux cas, donc vérifiez toujours la convention documentée pour l'API spécifique que vous appelez.

Un 422 peut-il signifier que le serveur a un bug ?

Cela peut arriver, si la règle de validation elle-même est fausse, par exemple en rejetant un format d'e-mail réellement valide. Mais un 422 par conception signifie que le serveur fonctionne comme prévu et s'oppose aux données, donc examinez la règle de validation réelle avant de supposer qu'elle est cassée.