Identifier un fichier refusé par la route des médias
Une intégration envoie une image à WordPress et reçoit une erreur comme rest_upload_no_data ou rest_upload_no_content_disposition. Vous voyez parfois une erreur 400 alors que le même fichier s’ajoute depuis la médiathèque. Ce guide traite le contenu de la requête de création d’un média, c’est-à-dire les octets du fichier et les indications qui disent au serveur comment les lire.
La route native des médias est /wp/v2/media dans l’API REST. Le préfixe public est souvent /wp-json, mais l’adresse complète dépend de l’installation. Une requête POST bien formée peut créer un élément de médiathèque et écrire un fichier. Les essais proposés se font donc sur une copie privée autorisée, avec un petit fichier de test et un compte prévu à cet effet. Les commandes ci-dessous supposent une installation qui expose cette API native et autorise le mode d’authentification décrit. Sur WordPress.com ou une autre plateforme gérée, vérifiez d’abord l’URL et le mécanisme d’accès indiqués pour votre site ; ne transposez pas ces exemples à une API de plateforme dont le contrat diffère.
Deux formes sont utiles : un corps brut composé des octets du fichier, ou un formulaire multipart dont une partie contient le fichier. Choisissez celle que votre client doit réellement produire. Si la requête atteint un autre serveur, si l’utilisateur n’a pas le droit de téléverser ou si la génération des miniatures échoue après création, la correction ne se trouve pas au même endroit.
Relever ce qui est envoyé et ce qui répond
Depuis le client ou les journaux d’intégration, repérez la tentative qui a échoué. Enregistrez la méthode, l’URL finale connue, le statut HTTP et le code JSON de WordPress s’il existe. Notez aussi le type annoncé pour le corps et le mode choisi dans le client. Un statut 400 sans autre détail ne permet pas de déterminer si un fichier manquait.
L’onglet Réseau du navigateur peut aider si l’envoi vient d’une page. Pour un script serveur, l’outil de journalisation du client est plus pertinent. N’exportez pas de requête brute avec ses cookies, son en-tête Authorization ou un fichier utilisateur. Faites un relevé ciblé avec le média témoin et des valeurs masquées.
- Vérifiez que la requête observée est bien le POST de création et non un GET de la médiathèque.
- Relevez le statut, le champ code de l’erreur et le message, en masquant les données privées.
- Notez si le corps est déclaré binaire, JSON ou multipart, et si la taille envoyée paraît plausible.
- Identifiez le logiciel ou l’étape qui construit la requête : formulaire, client HTTP, connecteur ou intermédiaire.
Confirmer la bonne URL et le droit de téléverser
Utilisez l’adresse HTTPS de la copie confirmée par son exploitant et la route REST qu’elle annonce. Si WordPress est installé dans un sous-dossier ou fait partie d’un réseau, vérifiez le chemin complet et le bon sous-site. Une redirection vers une connexion ou un autre domaine est une piste de routage ou d’accès. Identifiez sa destination avant de transmettre un secret ; n’ajoutez pas le suivi automatique des redirections aux exemples.
L’identité utilisée par l’intégration doit disposer du droit de téléverser des fichiers. Si vous attachez le média à un article dans la même requête, WordPress vérifie aussi le droit de modifier cet article. Évitez ce champ pour le premier test afin de séparer le transport du fichier des permissions sur le contenu. Un refus peut apparaître sous différents statuts selon l’étape et la version ; lisez le code et le message associés.
Un navigateur déjà connecté et un script distant n’utilisent pas nécessairement la même authentification. Pour le script, les exemples supposent un mot de passe d’application autorisé pour le compte de test, sur HTTPS. Ne réutilisez ni votre mot de passe habituel ni un secret d’une autre intégration. Si ce mode n’est pas disponible, utilisez le mécanisme approuvé sur cette copie.
Préparer un fichier témoin et un premier essai isolé
Choisissez une petite image PNG valide qui ne contient aucune donnée personnelle. Appelez-la diagnostic-rest.png pour suivre les exemples. Évitez un fichier vide, une extension changée sans conversion, une image récupérée chez un tiers ou un document destiné à être publié. Vérifiez que le client peut lire le fichier local et que la copie WordPress autorise ce type. Le nom du fichier aide à le retrouver, mais c’est l’identifiant de la fiche qui permet de distinguer deux tentatives.
Si vous disposez déjà du droit approprié, vérifiez une seule fois l’envoi du témoin dans Médias puis Ajouter un fichier média, ou via le bouton d’ajout de la médiathèque selon la version. Une réussite montre que le site sait traiter le témoin par l’interface ; elle ne prouve pas que le compte et les protections de l’intégration sont identiques. Si ce témoin échoue aussi par l’interface, relevez l’erreur avant de modifier le client REST.
Ne rattachez pas le témoin à un article réel. Notez les créations effectuées par l’interface et l’API pour les retirer à la fin. Si l’objectif immédiat est seulement d’ajouter un fichier et que l’interface fonctionne, elle reste une solution ponctuelle pendant le diagnostic du connecteur.
Choisir un seul format au lieu de combiner JSON et fichier
Dans un envoi brut, le corps contient les octets du fichier, du premier au dernier. Le client annonce le type de contenu et indique le nom du fichier dans Content-Disposition. Un corps composé du nom du fichier ou d’une chaîne JSON encodant son contenu ne reproduit pas cet envoi. Le contrôleur natif attend une forme précise ; écrire le chemin local dans le corps ne lui donne pas accès au disque du client.
En multipart, la requête contient des parties séparées. Le fichier est une partie nommée file, et le client génère les séparateurs et les en-têtes de chaque partie. Certains champs du formulaire peuvent voyager à côté du fichier, mais le premier essai peut se limiter à file. Ne forcez pas l’en-tête du message entier à image/png dans ce mode : seul le fichier porte ce type.
Choisissez le binaire si votre intégration fournit déjà un flux d’octets. Choisissez multipart si sa bibliothèque sait construire un formulaire avec fichier. Si elle ne sait produire que du JSON, cherchez sa fonction d’envoi de fichiers ou changez le client utilisé pour cette étape. N’alternez pas les formats et l’authentification dans le même essai.
Réparer un envoi binaire avec les deux en-têtes attendus
Lancez cet exemple dans un terminal privé de type sh, depuis le dossier du fichier témoin. Remplacez compte-api et l’URL par les valeurs de la copie autorisée. Le client curl est libre et ne nécessite aucun achat ni extension WordPress. L’option --user avec le seul identifiant fait demander le secret au terminal : saisissez le mot de passe d’application à cette invite. Ne l’ajoutez pas après un deux-points dans la commande. L’option --disable, placée en premier, évite d’appliquer la configuration curl par défaut de votre compte à cet essai.
L’argument --data-binary lit le fichier local grâce à @ et transmet ses octets. Les deux en-têtes indiquent le type réel et le nom à utiliser. Pour un autre fichier, adaptez ensemble le chemin local, le nom proposé et le type déclaré. L’exemple crée une fiche sur la copie s’il réussit ; ne rejouez pas la commande si le résultat tarde sans vérifier d’abord si un média a été créé.
Avec le contrôleur natif, une réussite complète attendue est HTTP 201 et un objet JSON contenant un identifiant. Si curl indique qu’il ne peut pas ouvrir le fichier local, corrigez le chemin côté client avant d’interpréter une erreur du serveur.
curl --disable --include --max-time 30 --user "compte-api" \
--header "Content-Type: image/png" \
--header 'Content-Disposition: attachment; filename="diagnostic-rest.png"' \
--data-binary "@diagnostic-rest.png" \
"https://preprod.example/wp-json/wp/v2/media"Réparer un formulaire multipart en joignant une partie file
Utilisez cet exemple si le client déclare un formulaire multipart ou si l’intégration veut joindre un fichier et des champs de formulaire. Il s’exécute sur la même copie, avec un fichier témoin local. Ne lancez pas les deux exemples par défaut : ils créent chacun une fiche si l’envoi réussit. Comparez-les seulement si la différence de transport doit être isolée.
L’option --form demande à curl de construire le formulaire. Le préfixe @ après file= signifie que la partie contient le fichier lu sur le disque. Sans lui, vous risquez d’envoyer le nom comme un texte. Le paramètre type de cette partie décrit l’image. Laissez curl produire l’en-tête multipart du message et son séparateur. Dans un autre client, choisissez l’option fichier pour la partie file et laissez sa bibliothèque fabriquer le formulaire de la même façon.
Si l’envoi réussit, conservez le statut et l’identifiant pour les comparer au résultat de l’intégration. Si curl réussit mais que le client habituel échoue, comparez les deux requêtes à données égales : nom de la partie, type, corps réel et URL. Ne changez pas les limites du serveur sur la seule base de cette différence.
curl --disable --include --max-time 30 --user "compte-api" \
--form "file=@diagnostic-rest.png;type=image/png" \
"https://preprod.example/wp-json/wp/v2/media"Interpréter le code précis avant de changer les réglages
Le code WordPress aide à savoir jusqu’où le traitement est arrivé. Des en-têtes absents sur un corps brut se corrigent dans la construction de cette requête. Sur un formulaire multipart, ajouter le même en-tête au message entier peut masquer une erreur de lecture du formulaire : vérifiez d’abord pourquoi aucune partie fichier utilisable n’est reconnue.
Le serveur peut retourner une réponse HTML ou une erreur réseau sans code WordPress. Comparez alors l’URL, le statut et les journaux de réception, sans conclure que le contrôleur a lu le fichier. Si plusieurs défauts se cumulent, réparez une seule étape et relevez le nouveau résultat.
- Avec
rest_upload_no_data, confirmez la lecture locale et la présence des octets ou de la partie fichier au point de réception. - Avec
rest_upload_no_content_type, vérifiez le type du corps brut ; en multipart, vérifiez d’abord que le client a correctement produit le formulaire. - Avec
rest_upload_no_content_dispositionourest_upload_invalid_disposition, contrôlez dans le parcours brut la présence de l’en-tête et d’un paramètre filename correct. - Avec
rest_upload_hash_mismatch, comparez le contenu réellement reçu au contenu qui a servi au calcul d’intégrité ; ne désactivez pas un contrôle exigé par l’intégration. - Avec un refus d’accès ou de route, corrigez l’identité ou l’adresse avant d’évaluer la taille et le format.
Déterminer si le fichier est perdu avant ou après WordPress
Si une requête correcte réussit avec un petit fichier mais échoue avec un fichier plus gros, relevez la taille du corps et la première couche qui le refuse. Une réponse 413 peut provenir du service devant WordPress. Pour un envoi multipart, PHP peut aussi rejeter le fichier ou le corps total selon ses limites effectives. Le corps du formulaire inclut plus que la taille de l’image seule. Si le corps dépasse la valeur de post_max_size, PHP peut laisser ses champs et fichiers analysés vides ; comparez aussi la limite upload_max_filesize et le journal du contexte PHP du site. Ces cas ne se corrigent pas en rajoutant Content-Disposition.
Demandez au responsable de comparer l’heure, l’URL, le statut et la taille observée par le client avec les journaux du premier serveur puis de PHP. Un proxy ou un filtre peut aussi refuser un type de requête sur une seule route. Faites corriger la règle précise lorsqu’elle est identifiée, sans enlever toute la protection de l’API. Si le même fichier est refusé par WordPress dans les deux modes, lisez son erreur de type, de quota ou d’écriture et traitez cette cause séparément.
Une création suivie d’un échec de traitement de l’image est encore un autre cas. Le fichier ou la fiche peut déjà exister alors que certaines tailles ne sont pas prêtes. Vérifiez la médiathèque avant de changer le client ou de renvoyer les mêmes octets.
Confirmer la création, puis vérifier l’usage du média
Lisez le statut et le corps de la réponse. Pour le parcours de création natif, HTTP 201 avec un identifiant d’élément est le résultat attendu. Dans la médiathèque de la même copie, retrouvez la fiche correspondant à cet identifiant et ouvrez l’image dans le parcours prévu. Un site peut stocker les fichiers sur un autre service ; vérifiez que l’adresse ou l’aperçu renvoyé correspond à ce stockage attendu. Ne supposez pas que l’image doit être publiquement accessible si l’environnement est privé.
Une réponse correcte ne valide pas tous les réglages de l’intégration. Si le connecteur doit ensuite renseigner le titre, le texte alternatif ou un article parent, vérifiez ces actions dans une seconde étape avec l’identifiant obtenu. Ne renvoyez pas le fichier seulement pour modifier le texte de sa fiche. La route de mise à jour vise l’identifiant existant.
- Relevez l’identifiant et le statut du média de test.
- Vérifiez la fiche et le fichier dans la médiathèque autorisée.
- Corrigez le client habituel et rejouez un contrôle témoin dans le même contexte.
- Comparez le résultat et vérifiez que l’intégration conserve l’identifiant au lieu de créer un doublon.
Revenir à la configuration précédente sans effacer le mauvais média
Si la modification du client casse un parcours qui fonctionnait, remettez sa version sauvegardée et refaites une lecture ou un essai autorisé sur la copie. Un retour de configuration n’efface pas les médias déjà écrits. Après un délai dépassé, la connexion peut s’être fermée alors que l’écriture ou le traitement se poursuivait. N’utilisez pas une répétition automatique comme première réponse à cet état incertain.
Recherchez les éléments de test par heure, nom et identifiant. Quand un en-tête X-WP-Upload-Attachment-ID est présent, il peut donner un identifiant à vérifier même si le traitement suivant a échoué. Son absence ne prouve pas que rien n’a été créé. Distinguez la tentative réalisée depuis l’interface de celle envoyée par l’API.
Sur la copie, retirez seulement les fiches de test confirmées depuis Médias puis Bibliothèque, en vérifiant qu’elles ne sont utilisées dans aucun contenu. La suppression définitive peut retirer le fichier associé ; n’utilisez pas une sélection groupée fondée uniquement sur un nom ressemblant. Révoquez le mot de passe d’application si vous l’avez créé exclusivement pour cette vérification. Ne touchez pas aux accès de l’intégration qui doivent rester en service.
Documenter le format attendu pour les prochains envois
Dans la documentation privée de l’intégration, notez l’URL de destination par environnement, la méthode, le format du corps et les en-têtes attendus. Si vous utilisez multipart, notez le nom exact de la partie. Si vous utilisez un corps brut, précisez que le client transmet des octets et que le nom annoncé doit correspondre au type réel. Conservez les limites vérifiées auprès du serveur plutôt que de déduire une taille autorisée d’un seul essai réussi.
L’équipe peut garder un petit fichier témoin sans donnée personnelle et une procédure de contrôle sur une copie isolée. Faites suivre l’identifiant renvoyé par WordPress dans les traces techniques, sans journaliser l’en-tête d’accès ni le contenu du fichier. Définissez aussi le traitement des réponses ambiguës : vérifier si le média existe avant de renvoyer le POST.
Si le blocage subsiste, transmettez au mainteneur l’heure, le statut, le code d’erreur, le mode d’envoi, la taille et le point où le fichier est encore observé. Une comparaison reproductible est plus utile qu’une copie intégrale de la requête. Elle permet de savoir qui doit corriger le client, l’autorisation ou la couche de réception.
