Per risolvere gli errori della WordPress REST API durante il salvataggio, individua la richiesta non riuscita e leggi la risposta del server. Il messaggio “La risposta non è una risposta JSON valida” può dipendere da una sessione scaduta, dai permalink, da un plugin o dalla configurazione del server. La risposta HTTP aiuta a distinguere queste cause.
Il mio consiglio è partire dalla risposta HTTP, evitando modifiche casuali. Prima proteggi il lavoro non salvato, poi segui una diagnosi che separi autenticazione, permessi e problemi infrastrutturali.
Come funzionano le richieste REST di WordPress
Perché l’editor comunica con gli endpoint
L’editor a blocchi usa la REST API per leggere e salvare contenuti, inviando richieste HTTP al server web. WordPress 4.7 ha integrato nel core gli endpoint dei contenuti nel dicembre 2016.
Le route predefinite comprendono /wp/v2/posts, /wp/v2/pages e /wp/v2/users, normalmente raggiungibili sotto /wp-json/. Ogni endpoint deve essere registrato e associato a un’operazione. I metodi HTTP mappano le azioni: GET legge i dati, POST crea contenuti e può aggiornarli, PUT indica un aggiornamento e DELETE elimina. Durante la diagnosi, considero normale anche un aggiornamento inviato con POST.
La documentazione distingue precisamente route ed endpoint REST: percorso e metodo HTTP devono corrispondere a un’operazione registrata.
Quale risposta si aspetta WordPress
L’editor deve ricevere una risposta JSON coerente. Una pagina HTML di accesso, un avviso PHP o un blocco del firewall possono rendere illeggibile la risposta.
REST deriva dalla tesi di Roy Fielding del 2000. I vincoli comprendono interfaccia uniforme, separazione client-server, statelessness, cacheabilità e architettura a strati; il codice eseguibile su richiesta è opzionale. Lo stesso disaccoppiamento tra client e server permette di usare WordPress come headless CMS. Un front end separato legge e invia contenuti tramite REST API.
Per correggere il salvataggio, serve capire quale livello interrompe questa comunicazione.
1. Individua la richiesta che non salva
Proteggi contenuti e ambiente di lavoro
Prima di ricaricare l’editor, copia altrove il testo non salvato. Le revisioni non sostituiscono una copia delle modifiche ancora presenti soltanto nel browser.
Prima di cambiare configurazioni, crea un backup di file e database. Preferisco eseguire le prove su staging, soprattutto quando il sito raccoglie ordini o richieste.
Su un e-commerce WooCommerce, disattivare un’estensione può interrompere pagamenti o integrazioni. Inoltre, un ripristino completo può sovrascrivere gli ordini successivi al backup. La mia guida all’assistenza WordPress per PMI approfondisce l’organizzazione degli interventi.
Leggi la scheda Rete del browser
Apri gli strumenti per sviluppatori, seleziona Rete e ripeti il salvataggio. Filtra le richieste Fetch/XHR oppure cerca wp-json.
Seleziona la richiesta fallita e annota URL, metodo, stato HTTP e orario. Nella scheda Risposta distingui il JSON da eventuali pagine HTML. Controlla anche gli header, in particolare Content-Type.
La Console aiuta a trovare errori JavaScript, ma da sola non identifica la risposta del server. Evita inoltre di condividere esportazioni delle richieste senza oscurare cookie, token CSRF e credenziali.
2. Interpreta lo stato HTTP e il messaggio JSON
Questi codici orientano la diagnosi, ma non identificano automaticamente il componente responsabile.
| Stato | Indizio principale | Primo controllo |
|---|---|---|
| 400 | Dati o parametri non validi | Corpo JSON e campi richiesti |
| 401 | Autenticazione assente o fallita | Credenziali e sessione |
| 403 | Accesso negato | Token di sicurezza, capability o firewall |
| 404 | Risorsa o route non trovata | Percorso, metodo e permalink |
| 413 | Richiesta troppo grande | Limiti di server o proxy |
| 429 | Troppe richieste | Policy o regole di rate limiting attive su server, reverse proxy o CDN |
| 500 | Errore interno | Log PHP e server |
Parti quindi dalla categoria indicata, poi confronta risposta e log.
Un errore REST generato da WP_Error può contenere code, message e data.status. Per esempio, rest_cookie_invalid_nonce indirizza verso la verifica del token di richiesta; rest_invalid_param indica un parametro rifiutato.
Anche una risposta HTTP 200 può far fallire il salvataggio se contiene HTML o avvisi PHP invece del JSON atteso.
Un codice 403 accompagnato dal marchio del firewall richiede invece una diagnosi diversa da un errore JSON prodotto da WordPress.
3. Ripristina autenticazione e nonce
Sessione dell’editor e nonce scaduto
Con l’autenticazione tramite cookie, WordPress richiede un nonce associato all’azione wp_rest. Il codice può generare questo token con wp_create_nonce( 'wp_rest' ) e inviarlo tramite X-WP-Nonce oppure _wpnonce.
Se il token manca, WordPress tratta la richiesta come non autenticata, anche quando esiste un cookie di accesso. Se è scaduto, può comparire un 403.
Dopo aver copiato il testo, rinnova l’accesso e riapri l’editor. Controlla inoltre che pannello e richieste usino lo stesso dominio e HTTPS. L’autenticazione valida, comunque, non concede automaticamente i permessi necessari.
Application Password e prova con curl
Per chiamate esterne, WordPress supporta le Application Password dalla versione 5.6. La documentazione sull’autenticazione descrive il loro utilizzo tramite Basic Authentication, che richiede HTTPS. Per script diagnostici e integrazioni server-to-server, sono una soluzione più immediata rispetto a flussi complessi come OAuth.
L’header Authorization contiene lo schema Basic seguito da username:password codificato in Base64. Base64 non cifra le credenziali.
In locale, define( 'WP_ENVIRONMENT_TYPE', 'local' ); in wp-config.php dichiara l’ambiente e consente questa modalità anche senza HTTPS. Non usarla per aggirare la protezione del sito pubblico.
Imposta le variabili dell’ambiente e prova soltanto su una bozza:
curl --user "$WP_USER:$WP_APP_PASSWORD"
--request POST
"$WP_URL/wp-json/wp/v2/posts/$POST_ID"
--header 'Content-Type: application/json'
--data '{"title":"Bozza di prova"}'
WP_APP_PASSWORD deve contenere la password applicativa, non quella principale. La richiesta modifica il titolo del contenuto indicato da POST_ID.
4. Controlla permalink, plugin e server
Distingui una route assente da un problema di riscrittura
Apri /wp-json/ sul dominio interessato. Poi confronta una lettura tramite /wp-json/wp/v2/posts con /?rest_route=/wp/v2/posts.
Se la seconda forma funziona e la prima restituisce 404, sospetta le regole di riscrittura. Da Impostazioni > Permalink, salva senza cambiare struttura.
Su Apache conserva una copia di .htaccess prima di modificarlo. Su Nginx le regole dipendono dalla configurazione del server.
Dopo una migrazione, controlla home e siteurl: entrambi devono usare HTTPS. Differenze nel protocollo possono causare redirect o blocchi REST. Evita sostituzioni SQL indiscriminate: possono danneggiare valori serializzati. Inoltre, una lettura pubblica riuscita non dimostra che il salvataggio autenticato funzioni.
Isola conflitti e leggi i log
Parti dai componenti modificati prima dell’errore, soprattutto sicurezza, cache, redirect e autenticazione. Disattivali singolarmente su staging e ripeti sempre la stessa richiesta.
Per registrare errori PHP, attiva temporaneamente WP_DEBUG e WP_DEBUG_LOG, mantenendo WP_DEBUG_DISPLAY su false. Non duplicare definizioni esistenti in wp-config.php.
Cerca il primo errore pertinente all’orario della prova. Un percorso dentro un plugin è un indizio, non una prova definitiva. Per blocchi del firewall, timeout o problemi PHP-FPM servono anche i log infrastrutturali.
Al supporto hosting invia URL, orario con fuso, stato HTTP e prove effettuate, senza password. Dopo la correzione, svuota soltanto le cache coinvolte.
5. Correggi i custom endpoint e i permessi
Se l’errore riguarda codice personalizzato, verifica che il custom endpoint sia registrato durante rest_api_init, tramite register_rest_route(), con un namespace riconoscibile e una permission_callback.
Organizza le API custom in un plugin dedicato o in un mu-plugin, invece di appesantire functions.php del tema attivo. Un errore fatale in functions.php può interrompere l’output JSON.
Questo esempio definisce un endpoint diagnostico riservato agli utenti con capability edit_others_posts:
<?php
add_action( 'rest_api_init', function () {
register_rest_route( 'af-diagnostica/v1', '/stato', array(
'methods' => 'GET',
'callback' => function () {
return new WP_REST_Response(
array( 'ok' => true ),
200
);
},
'permission_callback' => function () {
return current_user_can( 'edit_others_posts' );
},
) );
} );
Inserisci il codice in un plugin personalizzato su staging. La route /wp-json/af-diagnostica/v1/stato è il custom endpoint e richiede un’autenticazione valida.
Per i custom endpoints di scrittura, definisci la validazione e la sanitizzazione dei parametri. Il metodo dichiarato deve corrispondere all’operazione supportata dal controller: usa GET per leggere e DELETE per eliminare, se la route prevede queste operazioni.
Quando restituisci WP_Error, assegna uno stato HTTP appropriato. Senza uno stato esplicito, potresti ottenere un errore 500 poco informativo.
La guida ufficiale agli endpoint personalizzati approfondisce callback e autorizzazioni. Controlla anche le collisioni tra namespace e metodo richiesto: un percorso esistente potrebbe non accettare POST.
6. Mantieni la sicurezza e verifica il recupero
Non risolverei un 403 disattivando permanentemente firewall o controlli dei permessi. Individua la regola che blocca la richiesta e modifica soltanto quella pertinente.
HTTPS protegge i dati in transito. Le Application Password devono avere accessi coerenti con il compito e vanno revocate quando inutilizzate.
CORS riguarda le richieste del browser tra origini diverse; non autentica l’utente. Se curl funziona ma il browser blocca la chiamata, esamina origine, preflight e header consentiti. Non aggiungere autorizzazioni generiche senza considerarne l’effetto.
Dopo la correzione, salva una bozza, ricaricala e controlla che il contenuto persista. Prova anche login e funzioni interessate, compreso il checkout quando pertinente.
Infine, disattiva il debug temporaneo, proteggi i log e documenta causa e intervento. Per prevenire ricadute, affianca questi passaggi ai controlli di sicurezza WordPress.
Domande frequenti sugli errori REST API
L’editor classico risolve definitivamente il problema?
L’editor classico può aggirare alcuni sintomi, ma non corregge endpoint, permessi o configurazioni guaste. Le integrazioni che usano la REST API possono continuare a fallire.
Un errore REST indica un sito compromesso?
L’errore, da solo, non dimostra una compromissione. Amministratori sconosciuti, codice estraneo o redirect anomali richiedono invece un’indagine di sicurezza separata.
Ripristina il salvataggio senza modifiche inutili
Per correggere gli errori REST API di WordPress, parti dalla richiesta fallita e intervieni sul livello responsabile. Una modifica alla volta permette di distinguere una soluzione da una coincidenza.
Se il problema persiste, posso aiutarti come sviluppatore WordPress freelance con base a Roma/Ciampino. Lavoro anche online con aziende in tutta Italia.
Parliamo del tuo progetto web: indica messaggio, operazione bloccata e modifiche precedenti all’errore, senza inviare credenziali.
