« L’API REST a rencontré une erreur » : rest_no_route, 401, 403

L’API REST a rencontré une erreur

En anglais : The REST API encountered an error

Dans Outils, Santé du site, un test critique s’affiche : « L’API REST a rencontré une erreur ». Il est suivi du détail « Lors du test de l’API REST, une erreur s’est produite : », de l’adresse testée et d’une ligne « Réponse de l’API REST : (code) message ». Selon les cas, l’éditeur de blocs refuse aussi d’enregistrer, ou la console du navigateur affiche des erreurs comme rest_no_route, rest_forbidden ou rest_cookie_invalid_nonce pour une requête vers /wp-json/. L’erreur se constate dans l’administration, mais elle peut aussi casser un site headless, une application mobile ou un formulaire qui s’appuie sur l’API.

Ce que signifie cette erreur

L’API REST est le canal par lequel WordPress et d’autres applications dialoguent avec le serveur. Le message de Santé du site le rappelle : l’écran de l’éditeur s’appuie sur elle pour afficher et enregistrer vos publications. Le test est réalisé par get_test_rest_availability() (wp-admin/includes/class-wp-site-health.php). WordPress envoie depuis le serveur lui-même une requête wp_remote_get() vers /wp-json/wp/v2/types/post?context=edit, avec vos cookies, un nonce X-WP-Nonce et un délai de dix secondes.

Trois résultats sont possibles. Si wp_remote_get() renvoie une erreur de transport (résolution DNS, certificat SSL, délai dépassé), le test devient critique avec « L’API REST a rencontré une erreur » et affiche le code et le message de l’erreur de transport. Si le serveur répond avec un code différent de 200, le test est classé « recommandé » avec le titre « L’API REST a rencontré un résultat inattendu » et le code HTTP. Si la réponse est 200 mais que la clé capabilities est absente, le titre devient « L’API REST ne s’est pas correctement comportée » : le paramètre context n’a pas été traité correctement.

Les erreurs de routes ont leurs propres codes. rest_no_route (statut 404) signifie « Aucune route correspondante à l’URL et à la méthode de requête n’a été trouvée. » (wp-includes/rest-api/class-wp-rest-server.php). rest_forbidden signifie « Désolé, vous n’avez pas l’autorisation de faire cela. » : la fonction permission_callback de la route a refusé la requête, avec le statut 401 pour un visiteur non connecté et 403 pour un utilisateur connecté (rest_authorization_required_code(), wp-includes/rest-api.php). rest_cookie_invalid_nonce (statut 403) correspond à « La vérification du cookie a échoué » : le nonce X-WP-Nonce est absent de la session, expiré ou invalide.

Diagnostic rapide

Symptôme / constat	Cause probable	À vérifier
Santé du site : « Réponse de l’API REST : (http_request_failed) cURL error … »	Le serveur ne parvient pas à se joindre lui-même (DNS, SSL, pare-feu, délai)	Message d’erreur complet, test curl depuis le serveur
/wp-json/ renvoie 404 ou une page du thème	Réécriture d’URL absente, permaliens simples, règle serveur manquante	Réglages, Permaliens ; .htaccess ou configuration nginx
rest_no_route pour une route personnalisée	Route non enregistrée, mauvaise méthode ou mauvais espace de noms	register_rest_route(), hook rest_api_init
401 ou 403 rest_forbidden à l’enregistrement	Session expirée, droits insuffisants ou authentification non transmise	Reconnexion, rôle, en-tête Authorization
rest_cookie_invalid_nonce sur une page en cache	Nonce périmé servi par un cache de page	Exclusions du cache, durée de vie des pages

Les causes les plus fréquentes

1. Des permaliens ou des règles de réécriture défaillants : /wp-json/ n’atteint plus WordPress.
2. Un pare-feu, une règle ModSecurity ou une protection de l’hébergeur qui bloque les requêtes vers /wp-json/ ou les méthodes POST, PUT et DELETE.
3. Une extension de sécurité ou un code personnalisé qui désactive l’API pour les visiteurs ou la restreint via le filtre rest_authentication_errors.
4. Une requête du serveur vers lui-même impossible : DNS interne, certificat SSL invalide, authentification HTTP (htpasswd), page de maintenance ou défi anti-robot d’un CDN.
5. Une session expirée ou un nonce périmé, souvent à cause d’un cache de page qui conserve un ancien nonce.
6. Un en-tête Authorization supprimé par le serveur ou un proxy, qui empêche l’authentification par mot de passe d’application.

Solutions pas à pas

1. Lire le message exact

Relevez dans Santé du site la ligne « Réponse de l’API REST : (…) ». Le code entre parenthèses distingue immédiatement les familles : un code d’erreur de transport (http_request_failed, avec un message cURL) relève des solutions 3 et 4 ; un code numérique (404, 403, 401, 500) relève de la solution 2 ou 5. Pour une erreur de délai, voyez la fiche cURL error 28.

2. Tester l’URL avec curl

Depuis votre poste, puis depuis le serveur si possible, interrogez l’API en affichant l’état et les en-têtes :

curl -i https://www.exemple.fr/wp-json/
curl -i "https://www.exemple.fr/?rest_route=/"
curl -i "https://www.exemple.fr/wp-json/wp/v2/types/post"

Un document JSON avec le statut 200 est le résultat attendu. Si l’URL avec ?rest_route= fonctionne mais pas /wp-json/, le problème vient de la réécriture d’URL (solution 3). Si les deux échouent, cherchez du côté d’une extension ou du pare-feu (solutions 4 et 5).

3. Réparer les permaliens

Dans Réglages, Permaliens, choisissez un format autre que « Simple » (par exemple « Nom de l’article ») et cliquez sur « Enregistrer les modifications » : WordPress régénère ses règles de réécriture (rest-api.php ajoute les règles ^wp-json/… vers index.php?rest_route=). Avec WP-CLI :

wp rewrite structure '/%postname%/' --hard
wp rewrite flush --hard

Ces commandes écrivent dans le site : sauvegardez avant. Vérifiez ensuite la configuration du serveur. Sous Apache, le bloc standard de WordPress dans .htaccess doit être présent :

# BEGIN WordPress
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]
RewriteBase /
RewriteRule ^index\.php$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.php [L]
</IfModule>
# END WordPress

Sous nginx, la règle suivante dans le bloc server envoie toute URL inexistante vers WordPress :

location / {
	try_files $uri $uri/ /index.php?$args;
}

Si le site est au format de permaliens « Simple », l’API reste accessible par /?rest_route=/. La fiche pages en 404 malgré leur existence traite le sujet des permaliens en détail.

4. Réparer la requête du serveur vers lui-même

Quand Santé du site affiche une erreur de transport, le serveur ne parvient pas à interroger sa propre adresse. Vérifiez : que le nom de domaine se résout depuis le serveur (fichier /etc/hosts ou DNS interne), que le certificat SSL est valide (erreur « cURL error 60 » pour un certificat non reconnu), que le site n’est pas protégé par une authentification HTTP ou une page de maintenance, et que le CDN ne soumet pas le serveur à un défi anti-robot. Notre article sur les délais et erreurs de wp_remote_get explique comment WordPress traite ces échecs.

5. Isoler une extension ou un pare-feu

Désactivez temporairement les extensions de sécurité, de cache ou « d’optimisation » et refaites le test : si l’API répond, réactivez-les une à une. Cherchez aussi dans votre code un filtre rest_authentication_errors qui renvoie une erreur aux visiteurs. Pour un blocage par l’hébergeur ou par un pare-feu applicatif, relevez l’heure du test et demandez le journal du pare-feu (code 403 ou 406 sur /wp-json/). La fiche erreur 403 en détaille les causes.

6. Corriger les erreurs 401, 403 et de nonce

Pour rest_cookie_invalid_nonce, reconnectez-vous, rechargez la page d’édition et excluez les pages d’administration et les pages dynamiques de votre cache de pages. Pour une application tierce qui utilise un mot de passe d’application, vérifiez que l’en-tête Authorization parvient bien à PHP : la règle RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}] ci-dessus la transmet sous Apache ; avec PHP en CGI ou FastCGI, ajoutez CGIPassAuth On (Apache 2.4.13 et suivants). L’article 401 ou 403 : le code d’autorisation REST complète ce point, de même que notre article sur les d’application et l’API REST.

7. Côté développeur : vérifier la route

Un rest_no_route sur une route personnalisée signale un espace de noms ou une méthode erronés, ou une route enregistrée hors du hook rest_api_init. Un rest_forbidden signale une permission_callback qui renvoie false : elle est obligatoire et doit refléter vos droits réels.

add_action( 'rest_api_init', function () {
	register_rest_route( 'mon-plugin/v1', '/reglages', array(
		'methods'             => 'GET',
		'callback'            => 'mon_plugin_reglages',
		'permission_callback' => function () {
			return current_user_can( 'manage_options' );
		},
	) );
} );

Pour une route publique, déclarez explicitement 'permission_callback' => '__return_true'. Le guide sécuriser une API REST personnalisée avec permissions et nonces montre la démarche complète.

Prévenir l’erreur

• Ne désactivez pas l’API REST globalement : l’éditeur de blocs en dépend. Restreignez plutôt des routes précises, avec des contrôles de droits adaptés.
• Après une migration ou un changement d’hébergeur, ouvrez Santé du site et contrôlez que le test de l’API REST est « bon ».
• Excluez /wp-json/ et les pages d’administration du cache de pages.
• Documentez les règles de pare-feu applicatif et testez les routes critiques avec curl après chaque modification.

FAQ