HTTP 422 Contenu non traitable : signification et solutions

Ce que signifie cette erreur et comment la reconnaître

• Un navigateur, un client API, un service de monitoring ou un outil de vérification de site reçoit une réponse HTTP 422 Unprocessable Content.
• Le serveur renvoie une réponse HTTP : la requête a donc atteint un endpoint parlant HTTP ; la résolution DNS et la négociation TLS peuvent malgré tout fonctionner normalement.
• L’échec concerne une URL, une méthode HTTP, l’envoi d’un formulaire, un payload d’API ou une action utilisateur spécifique, plutôt que l’ensemble du site.
• La réponse peut contenir un corps d’erreur indiquant un champ, une valeur, un état ou une règle de validation non valide.
• Les en-têtes de réponse peuvent fournir des informations sur la mise en cache, l’authentification, le proxy, la limitation de débit, le suivi de la requête ou le serveur, afin d’aider à localiser la source.

Causes principales, classées par probabilité

Les causes les plus probables sont les suivantes :

1. Échec de validation applicative. Un champ obligatoire peut être absent, une valeur peut être hors de la plage autorisée ou une combinaison de champs individuellement valides peut être inacceptable pour l’opération.
2. La requête ne correspond pas à la méthode ou à la représentation attendue par la route. L’URL, la méthode HTTP, le type de contenu, la structure du corps ou les données encodées peuvent ne pas correspondre à ce que l’endpoint est conçu pour traiter.
3. État de ressource ou règle métier non valide. La requête peut être syntaxiquement valide mais impossible dans l’état actuel, par exemple lorsqu’une opération entre en conflit avec les règles de l’application.
4. Règle côté serveur, reverse proxy, CDN ou WAF. Un intermédiaire peut valider ou transformer la requête et renvoyer 422 avant que l’application ne la reçoive.
5. Modifications récentes du routage ou du déploiement. Une modification du schéma, du serializer, d’une règle de middleware ou d’une intégration en amont peut faire échouer des requêtes auparavant acceptées.
6. Contexte d’authentification ou d’autorisation. Ces éléments peuvent contribuer au problème lorsque l’application valide une opération authentifiée ou l’état d’une requête, mais un 422 seul ne doit pas être automatiquement diagnostiqué comme une erreur de connexion ou de permission. Vérifiez la réponse et les journaux pour le distinguer de 401 ou 403.

Comment corriger le problème

Si vous consultez le site web

1. Réessayez une fois et vérifiez la requête. Contrôlez l’URL, les valeurs sélectionnées dans le formulaire, les données importées et les champs obligatoires. Ne soumettez pas plusieurs fois la même action si elle peut créer un enregistrement ou déclencher une limite.
2. Utilisez le parcours normal du compte. Si l’action nécessite un compte, connectez-vous via l’interface habituelle du site et réessayez. Ne copiez pas de mots de passe, de cookies ou de tokens dans vos demandes d’assistance.
3. Vérifiez si l’échec concerne une seule action. Si les pages normales fonctionnent mais qu’un formulaire, un import ou une action de paiement renvoie 422, notez cette action, l’heure approximative et le message d’erreur visible.
4. Essayez uniquement un autre client approprié. Si le propriétaire du site l’autorise, une fenêtre privée ou un autre navigateur pris en charge peut aider à distinguer un problème local de formulaire ou de session d’une réponse côté serveur. Ne contournez pas les contrôles de sécurité.
5. Contactez le propriétaire du site si le problème persiste. Fournissez l’URL concernée, le type de requête s’il est connu, l’heure de l’échec et les détails d’erreur nettoyés de toute donnée sensible. N’envoyez pas d’identifiants, de cookies de session, de données de paiement ou de secrets d’API.

Si vous êtes développeur ou propriétaire du site

1. Capturez la requête et la réponse exactes. Notez la méthode HTTP, l’URL, les paramètres de requête, le type de contenu, les champs pertinents du corps, le statut, le corps de la réponse et ses en-têtes. Masquez les secrets et les données personnelles.
2. Confirmez que 422 est la réponse finale. Vérifiez les redirections, les réponses mises en cache ou un intermédiaire susceptible de masquer la réponse de l’application. Comparez le résultat avec une requête connue comme valide pour la même route.
3. Validez la requête par rapport au contrat de l’endpoint. Vérifiez les champs obligatoires, les types de données, les valeurs autorisées, l’encodage, le type de contenu, les identifiants de ressource ainsi que les éventuelles exigences d’ordre ou d’état. Distinguez la validation sémantique d’une syntaxe malformée, qui peut produire un autre statut.
4. Identifiez la couche qui génère la réponse. Utilisez les en-têtes distinctifs, les identifiants de requête, les journaux d’accès et applicatifs, les journaux du reverse proxy, les enregistrements du CDN ou les événements du WAF pour déterminer si le 422 provient de l’application ou d’un intermédiaire.
5. Comparez une requête en échec et une requête réussie. Modifiez un seul élément pertinent à la fois, par exemple la méthode, la valeur d’un champ, le type de contenu, l’état authentifié ou la ressource cible. Gardez la reproduction minimale afin de rendre la règle de validation réellement visible.
6. Examinez les modifications récentes. Vérifiez les déploiements, définitions de routes, schémas, serializers, middlewares, règles d’authentification, règles de proxy, comportement du cache et intégrations en amont autour du premier échec.
7. Appliquez la correction autorisée la plus ciblée. Corrigez le contrat de la requête, la règle de validation, la route ou la configuration de l’intermédiaire qui explique les éléments observés. Évitez les modifications générales des permissions, de la sécurité, du cache ou du proxy sans plan de retour arrière testé.
8. Retestez en toute sécurité et vérifiez les comportements voisins. Répétez si possible la même requête dans un environnement contrôlé, puis confirmez que les méthodes et routes associées renvoient toujours les statuts prévus. Si la modification concerne la production, suivez les procédures de gestion des changements et d’approbation du service.

Prévention et vérification du correctif

• Documentez, pour chaque endpoint, les méthodes acceptées, les types de contenu, les champs obligatoires, les valeurs autorisées et les réponses de validation attendues.
• Validez systématiquement les données des requêtes à la limite applicative appropriée et renvoyez un corps d’erreur exploitable qui ne contient pas de données sensibles.
• Ajoutez des tests pour les champs obligatoires, les valeurs non valides, les conflits d’état des ressources et les requêtes représentatives des clients.
• Surveillez les taux de 422 par route, méthode, client et déploiement afin de distinguer une régression du trafic de validation normal.
• Conservez le routage, le schéma, le proxy, l’authentification ainsi que la configuration du CDN et du WAF dans un contrôle de versions révisable.
• Conservez les identifiants de requête et les journaux pertinents assez longtemps pour relier une réponse HTTP au composant qui l’a générée, tout en masquant les secrets et les données sensibles.
• Testez les formulaires et méthodes d’API importants après les mises en production, les modifications de schéma et les mises à jour de configuration des intermédiaires.

Questions fréquentes