WordPress REST API erreur 404 : trouver et corriger la route

Pour corriger une WordPress REST API erreur 404, vérifiez d’abord l’URL complète sous /wp-json/, régénérez les permaliens dans Réglages, puis testez la route avec curl. Si /wp-json/ répond mais que votre endpoint renvoie 404, le problème vient généralement du namespace, du nom de route ou de son enregistrement dans rest_api_init. Si même /wp-json/ renvoie 404, examinez les règles de réécriture, le proxy, le cache et la configuration Apache ou Nginx.

Le code 404 signifie que la ressource demandée n’a pas été trouvée à cette adresse. Dans la REST API WordPress, cette réponse ne prouve donc pas que WordPress est arrêté. Elle peut signaler une mauvaise URL, une route personnalisée absente, une réécriture non appliquée ou une installation qui bloque l’API. La bonne méthode consiste à tester successivement l’index de l’API, la collection native, puis la route métier.

Comprendre l’erreur 404 de la REST API WordPress

La REST API native est généralement disponible à l’adresse https://exemple.fr/wp-json/. Cet index décrit les namespaces et les routes accessibles. Une collection comme /wp-json/wp/v2/posts sert à lire ou manipuler les articles selon les droits. Une route personnalisée peut utiliser un namespace comme mon-outil/v1 et un chemin comme rapport.

Une erreur 404 peut donc apparaître à plusieurs niveaux. Le domaine peut être incorrect, le sous-répertoire de WordPress peut manquer, le namespace peut contenir une faute ou l’endpoint peut ne pas être enregistré. Il faut aussi distinguer une 404 HTML produite par le serveur d’une réponse JSON WordPress contenant un code et un message. Cette différence indique où chercher.

# Tester l’index puis une collection native
curl -i https://exemple.fr/wp-json/
curl -i https://exemple.fr/wp-json/wp/v2/posts

# Afficher uniquement le statut HTTP
curl -sS -o /dev/null -w '%{http_code}n' 
  https://exemple.fr/wp-json/

Une réponse 200 sur l’index confirme que le préfixe fonctionne. Une réponse 200 ou 401 sur une collection montre que la route existe, même si elle exige une authentification. Une 404 systématique sur toutes les routes oriente plutôt vers les permaliens ou le serveur. Une 404 limitée à votre endpoint oriente vers le code PHP.

Vérifier l’URL wp-json et le sous-répertoire

La première cause est une URL construite comme si WordPress était installé à la racine alors qu’il se trouve dans un sous-dossier. Un site installé dans /blog utilise par exemple https://exemple.fr/blog/wp-json/. Une application headless qui appelle /wp-json/ à la racine obtiendra alors une 404 parfaitement logique.

Ne concaténez pas manuellement le domaine et le chemin dans chaque client. Demandez à WordPress son URL REST avec rest_url() côté PHP ou utilisez la valeur fournie par la configuration de l’application. Contrôlez aussi les variantes avec et sans slash final, le protocole HTTPS et les redirections entre le domaine principal et une version www.

// Générer l’URL depuis WordPress
$endpoint = rest_url( 'wp/v2/posts' );

// Inspecter les valeurs utiles
echo esc_url( home_url() );
echo esc_url( rest_url() );

Pour une intégration JavaScript, injectez l’URL depuis PHP plutôt que de supposer que le site est installé à la racine. Pour un script Python ou Node.js, stockez l’URL de base dans une variable d’environnement. Évitez les doubles préfixes comme /wp-json/wp-json/ et les appels vers /wp/v2/posts sans le namespace wp-json.

Vérifiez également que vous appelez le bon domaine après une migration. Le DNS, le CDN ou un environnement de préproduction peut répondre avec une page 404 tandis que le site de production possède bien la route. Utilisez curl -I et regardez l’en-tête Location pour repérer une redirection inattendue.

Régénérer les permaliens sans modifier les articles

Une modification de structure d’URL, une migration ou une extension peut laisser des règles de réécriture obsolètes. Dans WordPress, ouvrir Réglages, Permaliens puis cliquer sur Enregistrer les modifications régénère les règles sans changer les permaliens existants. Il n’est pas nécessaire de choisir une nouvelle structure.

Cette opération est souvent la correction la plus rapide quand l’index /wp-json/ renvoie 404 alors que WordPress fonctionne normalement. Videz ensuite le cache de page et du CDN, car une ancienne réponse peut rester servie. Testez avec une fenêtre privée ou un paramètre de requête temporaire, sans publier ce paramètre dans les liens canoniques.

# Avec WP CLI, régénérer les règles de réécriture
wp rewrite flush

# Afficher la structure active
wp option get permalink_structure

# Tester l’API après l’opération
curl -sS -D - -o /tmp/wp-json.json https://exemple.fr/wp-json/

Sur un hébergement mutualisé, vérifiez que le fichier .htaccess est présent à la racine de l’installation et que le serveur autorise les overrides nécessaires. Ne remplacez pas un fichier existant par un modèle trouvé au hasard. Sauvegardez-le, comparez les règles propres à l’hébergement et demandez au support d’intervenir si Apache ignore les directives.

Avec Nginx, le fichier .htaccess n’est pas lu. Les règles doivent être définies dans la configuration du serveur ou dans le proxy. Une migration de Apache vers Nginx peut ainsi casser l’API alors que les fichiers WordPress sont inchangés.

Contrôler une route personnalisée et son namespace

Si les routes natives répondent mais que votre endpoint renvoie 404, relisez l’appel à register_rest_route(). La fonction doit être exécutée sur l’action rest_api_init. Le namespace et le chemin utilisés par le client doivent correspondre exactement à ceux déclarés. Une différence de pluriel, de majuscule ou de version suffit à produire une route introuvable.

Le namespace contient généralement le nom du produit et sa version, par exemple mon-outil/v1. Le second argument décrit le chemin, ici rapport. L’URL finale sera /wp-json/mon-outil/v1/rapport. Le callback et la permission sont séparés de l’adresse. Une erreur dans permission_callback produit plutôt une réponse d’autorisation, pas une route absente.

add_action( 'rest_api_init', function () {
    register_rest_route(
        'mon-outil/v1',
        '/rapport',
        [
            'methods'             => WP_REST_Server::READABLE,
            'callback'            => 'mon_outil_lire_rapport',
            'permission_callback' => '__return_true',
        ]
    );
} );

Utilisez get_rest_url() ou l’index de l’API pour confirmer que la route est réellement enregistrée. Une extension inactive, un fichier non chargé ou une erreur PHP avant l’action peut empêcher l’enregistrement. Consultez le journal de debug pendant le chargement de l’extension et vérifiez que le code est placé dans le bon plugin ou dans le thème actif.

Depuis les versions modernes de WordPress, une route personnalisée doit déclarer explicitement permission_callback. Ajoutez cette fonction même pour une route publique, puis testez l’endpoint après avoir vidé les caches PHP. Une route qui n’apparaît pas dans /wp-json/ n’est pas un problème de permission, elle n’est pas enregistrée dans la requête actuelle.

Inspecter le code de réponse et les journaux

Ne vous contentez pas du message affiché par le navigateur. Une page 404 HTML peut venir du serveur, du CDN ou de WordPress. Avec curl -i, notez le statut, le type de contenu, les en-têtes de cache et les éventuelles redirections. Une réponse JSON avec rest_no_route indique que WordPress a reçu la requête mais ne connaît pas cette combinaison de méthode et de chemin.

# Conserver la réponse et les en-têtes
curl -sS -D /tmp/headers.txt 
  -o /tmp/body.json 
  https://exemple.fr/wp-json/mon-outil/v1/rapport

cat /tmp/headers.txt
cat /tmp/body.json

Une route peut exister pour GET mais pas pour POST, ou inversement. Testez la méthode réellement utilisée par le client. Une requête OPTIONS envoyée par le navigateur lors d’un appel CORS peut aussi échouer si le serveur ne répond pas correctement au pré-vol. Pour un diagnostic de délais et de réseau, consultez notre guide sur les erreurs curl 28 et curl 7 de la REST API WordPress.

Activez temporairement WP_DEBUG_LOG sans afficher les erreurs aux visiteurs. Reproduisez une seule fois la 404, puis recherchez le nom de l’extension et de la route dans wp-content/debug.log. Une erreur fatale peut empêcher le hook d’être exécuté. Désactivez le mode debug après le diagnostic et protégez le journal contre la lecture publique.

Écarter le cache, le CDN et les règles de sécurité

Les routes REST personnalisées ne doivent pas être mises en cache comme une page publique si leur réponse dépend de l’utilisateur. Un cache peut conserver une 404 ancienne après le premier appel, ou renvoyer une réponse d’un environnement différent. Purgez le cache de page, le cache objet, le CDN et l’opcache selon les outils disponibles, puis retestez directement l’origine si possible.

Les extensions de sécurité peuvent bloquer /wp-json/ ou masquer certaines routes. Ne désactivez pas toutes les protections sur un site exposé. Comparez plutôt les journaux du WAF, le code de réponse et l’heure du test. Une 401 indique une authentification manquante, une 403 une permission refusée, tandis qu’une 404 indique surtout une ressource ou une route non trouvée. Notre guide sur la correction d’une erreur 401 de la REST API WordPress traite le cas d’authentification.

# Tester avec un cache explicitement contourné
curl -sS -D - 
  -H 'Cache-Control: no-cache' 
  'https://exemple.fr/wp-json/?nocache=diagnostic'

# Examiner les redirections
curl -sS -I -L https://exemple.fr/wp-json/

Un proxy inverse peut modifier le chemin transmis à WordPress. Vérifiez que la configuration conserve le préfixe, les paramètres de requête et le protocole. Dans un montage headless, comparez l’URL publique, l’URL interne et le chemin du reverse proxy. Une réécriture qui retire wp-json ou ajoute un segment provoque une 404 qui semble mystérieuse côté application.

Tester l’API depuis PHP, JavaScript et Python

Reproduisez la même URL avec plusieurs clients pour séparer un problème serveur d’un problème d’intégration. Si curl fonctionne mais que JavaScript reçoit 404, inspectez l’URL finale dans DevTools. Si les deux échouent mais qu’une route native fonctionne, relisez l’enregistrement de l’endpoint. Si seule une méthode échoue, comparez la déclaration methods.

import requests

base = 'https://exemple.fr/wp-json/'
r = requests.get(base, timeout=15)
print(r.status_code, r.headers.get('content-type'))
print(r.text[:300])

route = base + 'mon-outil/v1/rapport'
r = requests.get(route, timeout=15)
print(r.status_code, r.text[:300])

Côté navigateur, utilisez l’URL injectée par WordPress et affichez uniquement le statut, jamais les secrets ou les données privées. Vérifiez le domaine effectif après une redirection. Pour les appels authentifiés, ne placez pas un mot de passe d’application dans le code distribué au public. Le secret doit rester côté serveur.

Une application React, mobile ou Node.js peut aussi appeler une ancienne version du namespace restée dans une variable d’environnement. Loguez l’URL construite après masquage du domaine privé et comparez-la avec l’index REST actuel. Cette vérification élémentaire révèle souvent une version v0 au lieu de v1.

Checklist de résolution d’une 404 REST API

Suivez cette séquence, sans modifier plusieurs couches à la fois. Testez d’abord /wp-json/, puis /wp-json/wp/v2/posts. Contrôlez le sous-répertoire, les redirections et les permaliens. Ensuite seulement, inspectez le namespace personnalisé, le hook rest_api_init, la méthode HTTP et les logs. Terminez par la purge du cache et un test depuis l’environnement réel.

# Séquence minimale
for url in 
  https://exemple.fr/wp-json/ 
  https://exemple.fr/wp-json/wp/v2/posts 
  https://exemple.fr/wp-json/mon-outil/v1/rapport
do
  printf '%s ' "$url"
  curl -sS -o /dev/null -w '%{http_code}n' "$url"
done

Consignez la cause et la correction dans la documentation du projet. Une 404 apparue après une migration doit faire vérifier les règles serveur et l’URL de base. Une 404 apparue après une mise à jour de plugin doit faire vérifier l’extension et son hook. Une 404 qui ne concerne qu’un utilisateur doit faire vérifier le cache personnalisé et le contexte de la requête.

Pour aller plus loin dans les permissions, les routes et la mise en cache, consultez notre guide avancé des développeurs sur la REST API WordPress. Si votre objectif est de protéger l’API, le guide de sécurisation REST, authentification, rate limiting et CORS complète ce dépannage.

FAQ sur l’erreur 404 de la REST API WordPress

Pourquoi la REST API WordPress renvoie-t-elle 404 ?

La REST API WordPress renvoie 404 lorsque l’URL, le sous-répertoire, le namespace ou la route demandée n’existe pas dans le contexte du serveur. Des permaliens non régénérés, une réécriture cassée, un cache ancien ou une extension inactive sont aussi des causes fréquentes.

Comment tester si wp-json fonctionne dans WordPress ?

Appelez https://votre-domaine.fr/wp-json/ avec curl -i ou ouvrez cette adresse dans un navigateur. Une réponse JSON contenant les namespaces confirme que l’index de la REST API est accessible.

Comment réparer une REST API WordPress 404 après une migration ?

Vérifiez l’URL du site, le sous-répertoire, les redirections HTTPS et les règles de réécriture, puis enregistrez de nouveau les permaliens. Avec Nginx, contrôlez la configuration du serveur, car le fichier .htaccess n’est pas utilisé.

Pourquoi une route personnalisée WordPress n’apparaît-elle pas ?

La route peut ne pas être enregistrée parce que le code n’est pas chargé, que l’action rest_api_init n’est pas utilisée, que le namespace est différent ou qu’une erreur PHP interrompt l’exécution. Inspectez l’index REST et le journal de debug.

Une erreur 404 REST API vient-elle d’un problème de permission ?

En général, une permission insuffisante produit plutôt une erreur 401 ou 403. Une 404 indique d’abord une route absente, une mauvaise méthode HTTP ou une réécriture défaillante, même si une extension de sécurité peut volontairement masquer une ressource.

Sources utiles : documentation officielle de la REST API WordPress, routes et endpoints, référence register_rest_route, référence du hook rest_api_init, commande WP CLI rewrite flush, documentation du debug WordPress.

G
WP Admin Lab

Architecte web full-stack. WordPress, performance, data et sécurité. Notes de terrain, tests reproductibles et retours d'expérience.