API REST WordPress renvoyant une erreur 404

Ce que signifie cette erreur et comment la reconnaître

• L’ouverture de /wp-json/ renvoie une page HTTP 404 au lieu du JSON de l’index de l’API REST.
• Une application JavaScript, une application mobile, un client REST, un éditeur ou une intégration signale 404 Not Found pour une requête API WordPress.
• Le site public WordPress se charge normalement alors que les requêtes REST échouent.
• ?rest_route=/ fonctionne alors que le chemin convivial /wp-json/ renvoie une erreur 404.
• L’index de l’API se charge, mais un plugin ou un endpoint personnalisé renvoie une erreur 404.
• L’outil Santé du site WordPress signale que l’API REST est indisponible ; il faut toutefois vérifier le corps de la réponse et le code d’état pour en identifier la source.

Causes principales, classées par probabilité

1. Règles de réécriture des permaliens obsolètes ou absentes. Ce problème survient souvent après une migration, une modification des permaliens, un changement de serveur ou un déploiement incomplet.
2. Le serveur web ou le proxy ne transmet pas /wp-json/ à WordPress. La prise en charge des réécritures Apache, le routage try_files de Nginx, la correspondance avec la racine des documents ou les paramètres de l’hôte virtuel peuvent être incorrects.
3. Une règle de sécurité, de pare-feu, de CDN, de cache ou d’hébergement renvoie une erreur 404. Certains contrôles masquent les requêtes bloquées en renvoyant une erreur « introuvable » plutôt qu’une erreur « interdit ».
4. Un plugin ou un thème modifie le comportement REST. Il peut supprimer des routes, restreindre l’accès ou filtrer les réponses REST.
5. Un seul endpoint personnalisé ou fourni par un plugin est incorrect. La requête peut utiliser un namespace, une route, une version, une méthode HTTP ou un identifiant de ressource incorrect, ou la route peut ne pas être enregistrée.
6. La requête cible la mauvaise installation ou le mauvais site. Les changements de domaine, les installations dans un sous-répertoire, les redirections, les paramètres obsolètes de l’application et les réponses mises en cache peuvent laisser les clients utiliser un ancien chemin de base de l’API.

Comment corriger le problème

1. Confirmer l’étendue et la source de l’erreur 404

Notez le chemin exact de la requête, le code d’état HTTP, le corps de la réponse, ses en-têtes, la méthode de requête et l’horodatage. Vérifiez si la réponse semble provenir de WordPress, du serveur web, d’un proxy inverse, d’un CDN ou d’une couche de sécurité. N’incluez pas de jetons d’accès, de cookies, de mots de passe ni de données privées de réponse dans les enregistrements de diagnostic.

Testez l’index de l’API REST à l’adresse /wp-json/ depuis un client approprié. Si l’index renvoie du JSON mais qu’un seul endpoint renvoie une erreur 404, passez directement à l’étape 5. Si l’index lui-même renvoie une erreur 404, poursuivez.

2. Actualiser les règles de réécriture WordPress

Dans le tableau de bord WordPress, ouvrez Réglages → Permaliens et cliquez sur Enregistrer les modifications sans modifier la structure de permaliens sélectionnée. Cette opération actualise la configuration de réécriture de WordPress.

Testez à nouveau /wp-json/. Si l’automatisation du déploiement ou le panneau de contrôle de l’hébergeur gère la configuration du serveur, confirmez que les paramètres de réécriture sont conservés et ne sont pas écrasés lors du déploiement suivant.

3. Comparer le chemin convivial avec la route alternative

Testez l’API REST à l’aide de l’alternative de WordPress basée sur un paramètre de requête : ajoutez ?rest_route=/ à l’adresse d’accueil normale du site. Utilisez le schéma, le nom d’hôte et le chemin d’installation réels. Une installation dans un sous-répertoire peut nécessiter que ce chemin reste inclus dans la requête.

• L’alternative fonctionne mais /wp-json/ échoue : WordPress peut traiter les requêtes REST ; examinez donc les réécritures d’URL conviviales, les paramètres de l’hôte virtuel, le routage du proxy, la correspondance avec la racine des documents et les changements liés à la migration.
• Les deux échouent : examinez les contrôles de sécurité, le routage du front controller du serveur, le comportement de WordPress et des plugins, ainsi que le chemin configuré du site ou de l’installation.
• Les deux requêtes d’index fonctionnent mais une route personnalisée échoue : diagnostiquez cet endpoint spécifiquement à l’étape 5.

4. Vérifier le routage du serveur web, du proxy et de la sécurité

Pour Apache, demandez à un administrateur autorisé de vérifier que la prise en charge des réécritures est activée pour le répertoire WordPress, que les règles de réécriture du site sont présentes et qu’elles sont autorisées par la configuration de l’hôte virtuel. Pour Nginx ou un proxy inverse, vérifiez que les requêtes atteignent le front controller de WordPress et que /wp-json/ n’est pas traité comme un fichier statique absent.

Examinez les journaux et règles concernés dans l’ordre suivant :

1. Journaux d’accès et d’erreur du serveur web pour la requête en échec.
2. Règles et entrées de cache du CDN, du répartiteur de charge et du proxy inverse.
3. Plugins WordPress de sécurité, de pare-feu, de protection de connexion et de contrôle REST.
4. Règles WAF au niveau de l’hébergeur susceptibles de classer le chemin, la méthode ou les en-têtes de la requête comme bloqués.

Effectuez une seule modification contrôlée à la fois, notez le paramètre d’origine et purgez uniquement le cache concerné après autorisation. Ne désactivez pas largement un pare-feu ou un plugin de sécurité en production sans plan de maintenance approuvé. Si une règle de sécurité est en cause, autorisez précisément le chemin et les méthodes REST requis au lieu de contourner toute la protection.

5. Diagnostiquer un endpoint introuvable

Confirmez le namespace exact de l’endpoint, sa route, son segment de version, sa méthode HTTP, son chemin final et son identifiant de ressource. Comparez la requête avec la documentation de la route ou le code d’enregistrement fourni par le plugin ou l’application.

Vérifiez que :

• Le plugin ou le thème responsable est actif dans l’environnement testé.
• L’enregistrement de la route s’exécute lors de l’initialisation REST.
• La route possède le callback de permission attendu et n’est pas omise conditionnellement pour la requête actuelle.
• Le client utilise le chemin de base de l’API du site actuel et non un ancien domaine, sous-répertoire ou paramètre d’application mis en cache.
• La ressource demandée existe réellement. L’absence d’un article, utilisateur, produit ou autre ressource peut produire légitimement une erreur 404 au niveau de l’endpoint, même lorsque l’API REST fonctionne correctement.

Consultez l’index de l’API ou la réponse de découverte des routes lorsqu’elle est disponible. Si la route attendue est absente, examinez son enregistrement, l’état du plugin, le namespace et la configuration propre à l’environnement plutôt que de considérer le problème comme une panne générale de REST.

6. Vérifier à nouveau après chaque modification contrôlée

Retestez depuis un navigateur, un client API autorisé et, le cas échéant, l’application qui a signalé l’erreur. Comparez le code d’état, les en-têtes de réponse, le corps de la réponse et l’origine de la réponse avant et après chaque modification. Restaurez les changements de diagnostic temporaires et documentez la configuration finale des réécritures, du pare-feu, du cache, du proxy ou du plugin.

Prévention et vérification du correctif

• Ajoutez un test de bon fonctionnement de l’API REST pour /wp-json/ et pour chaque route personnalisée critique à vos contrôles de migration et de déploiement.
• Maintenez la cohérence de l’URL du site WordPress, de l’URL d’accueil, de la racine des documents et de la configuration des sous-répertoires entre les environnements.
• Gérez la configuration des réécritures, les règles du proxy, les politiques du pare-feu et le comportement du cache comme des paramètres de déploiement documentés plutôt que comme des modifications de serveur non documentées.
• Vérifiez les changements des plugins de sécurité et du WAF pour évaluer leurs effets sur les requêtes REST authentifiées et non authentifiées.
• Surveillez le code d’état et l’origine de la réponse pour les appels API importants afin de distinguer une erreur 404 générée par un proxy d’une erreur 404 générée par WordPress.
• Documentez les namespaces personnalisés, les routes, les méthodes prises en charge, le comportement des permissions et le plugin ou thème responsable de chaque endpoint.