HTTP 415 Unsupported Media Type : signification et solutions

Ce que signifie cette erreur et comment la reconnaître

• Un client API, un formulaire de navigateur, un outil d’upload, un contrôle de monitoring ou une application signale 415 Unsupported Media Type.
• La réponse peut concerner un seul endpoint, une seule méthode HTTP ou un seul format de requête, tandis que les autres pages et routes continuent de fonctionner.
• Une requête peut échouer après une modification du format du corps, de Content-Type, de l’encodage du contenu, du type d’upload ou de la bibliothèque cliente.
• Les en-têtes de réponse peuvent révéler le serveur, le proxy ou le CDN à l’origine de la réponse, ainsi que des informations sur la mise en cache, l’authentification, les redirections ou les limites de débit.
• La résolution DNS et la négociation TLS peuvent réussir parce qu’une réponse HTTP a été reçue ; ces vérifications ne prouvent pas que le contenu de la requête était accepté.

Causes principales, classées par probabilité

1. Type de média de requête non pris en charge : L’endpoint n’accepte pas la valeur envoyée dans Content-Type, par exemple lorsque des données de formulaire sont envoyées à une route qui n’accepte que le JSON.
2. En-tête de requête incorrect ou manquant : Le client omet Content-Type, envoie une faute de frappe ou décrit le corps comme étant dans un format différent de son format réel.
3. Encodage du contenu non pris en charge : La requête utilise une compression ou un encodage de transfert que le composant destinataire ne peut pas traiter.
4. Endpoint ou méthode incorrect : La requête est envoyée à une route qui attend une autre représentation, un autre format d’upload ou une autre méthode HTTP.
5. Validation par un proxy, un CDN, un WAF ou un serveur web : Un intermédiaire rejette la requête avant qu’elle n’atteigne l’application, ou applique des règles différentes des exigences documentées par l’application.
6. Modification récente de l’application ou de la configuration : Un déploiement, une modification du routage, une mise à jour du parseur, une intégration d’authentification ou une règle de proxy modifie les formats de requête acceptés.

Le code d’état seul n’identifie pas le composant responsable. Confirmez les détails de la requête et les logs correspondants avant d’attribuer la cause à l’authentification, aux permissions, aux limites ou à la configuration en amont.

Comment corriger le problème

Pour les visiteurs et les utilisateurs non techniques

1. Réessayez exactement la même action une fois. Confirmez l’URL et, le cas échéant, l’action d’upload ou de formulaire que vous avez sélectionnée. Évitez d’envoyer plusieurs fois la même requête.
2. Utilisez le parcours de connexion habituel. Si l’endpoint nécessite un compte, connectez-vous via l’interface habituelle du site plutôt que de modifier manuellement les en-têtes de requête ou les cookies.
3. Vérifiez le fichier ou le contenu envoyé. Si l’erreur survient pendant un upload ou l’envoi d’un formulaire, utilisez le format demandé par le site et évitez de renommer un fichier sans le convertir.
4. Essayez l’interface prise en charge par le site. Si un outil API, une extension de navigateur ou une intégration personnalisée échoue, comparez son comportement avec le formulaire web ou l’application habituellement utilisés par le site.
5. Contactez le propriétaire du site si le problème persiste. Indiquez l’URL ou la fonctionnalité concernée, l’heure approximative, le résultat HTTP 415 et l’action qui a échoué. N’envoyez pas de mots de passe, cookies, jetons d’autorisation ni contenu privé de fichiers.

Pour les développeurs et les clients API

1. Capturez la structure complète de la requête. Notez la méthode, le chemin de l’URL, les paramètres de requête, Content-Type, l’encodage du contenu, la valeur Accept pertinente et une description assainie du corps. Ne journalisez pas inutilement les secrets ou les données personnelles.
2. Comparez la requête avec le contrat de l’endpoint. Vérifiez que la route et la méthode acceptent la représentation envoyée. Par exemple, confirmez si l’endpoint attend du JSON, des données encodées dans un formulaire, des données de formulaire multipart, du XML ou un format d’upload particulier.
3. Faites correspondre la déclaration au corps. N’étiquetez pas des données de formulaire comme du JSON et n’envoyez pas un corps compressé sans l’encodage pris en charge correspondant. Laissez la bibliothèque cliente construire les délimiteurs multipart lorsqu’elle propose cette fonctionnalité.
4. Utilisez une reproduction minimale. Supprimez autant que possible les champs facultatifs et les middleware sans rapport, puis répétez la même requête avec un corps dont la prise en charge est connue. Conservez la requête d’origine pour comparaison.
5. Inspectez la réponse. Vérifiez le statut, Content-Type, les indicateurs de mise en cache, les identifiants du serveur ou du proxy, les redirections et le corps éventuel de l’erreur. Une réponse générée par une gateway peut ne pas refléter la validation propre à l’application.
6. Consultez les logs de la couche responsable. Faites correspondre l’horodatage de la requête, la route et l’identifiant de corrélation ou de requête avec les logs de l’application, du serveur web, du reverse proxy, du CDN ou du WAF.
7. Appliquez la correction la plus ciblée. Corrigez l’en-tête client, le sérialiseur, le format d’upload, le contrat de la route ou la règle d’intermédiaire limitée au périmètre nécessaire. Ne désactivez pas globalement la validation, l’authentification ou le filtrage de sécurité en première intention.
8. Retestez et vérifiez les comportements associés. Répétez la requête d’origine, puis testez le même endpoint avec ses formats pris en charge et vérifiez que les routes associées renvoient toujours les codes d’état attendus.

Pour les propriétaires et opérateurs de sites

1. Reproduisez l’échec avec le même type de client et la même méthode de requête, en capturant les en-têtes assainis et les temps d’exécution.
2. Déterminez si le code 415 a été généré par l’application, le serveur web, le reverse proxy, le CDN ou le WAF en comparant les en-têtes de réponse et les logs de chaque couche.
3. Examinez les déploiements récents et les modifications du routage, de l’analyse des requêtes, du traitement des uploads, de la transmission par proxy, de l’encodage du contenu et des règles de sécurité.
4. Vérifiez que les caches ou les intermédiaires ne servent pas une réponse mise en cache inappropriée pour la requête.
5. Corrigez le contrat de la route ou du client concerné, documentez les formats acceptés et conservez suffisamment de logs pour confirmer la correction.
6. Si la requête n’est volontairement pas prise en charge, assurez-vous que le comportement de l’endpoint et la documentation destinée aux clients indiquent clairement le format accepté.

Prévention et vérification du correctif

• Documentez les méthodes HTTP, types de média, encodages et formats d’upload acceptés pour chaque endpoint important.
• Utilisez des tests automatisés pour les types représentatifs de requêtes JSON, de formulaires, multipart et autres formats pris en charge après toute modification de l’application ou du proxy.
• Gérez le routage, l’analyse des requêtes, la configuration du proxy, du CDN et du WAF dans un contrôle de version avec des modifications soumises à revue.
• Surveillez les codes d’état par route et par méthode au lieu de traiter toutes les réponses 4xx comme une seule catégorie.
• Conservez les identifiants de corrélation ainsi que les logs assainis de l’application et des intermédiaires pendant la durée de conservation appropriée.
• Faites échouer clairement les intégrations clientes lorsque les types de média acceptés par le serveur changent et testez-les par rapport au contrat documenté.

Questions fréquentes