Error de REST API en WordPress y cómo solucionarlo

Qué es la REST API de WordPress y por qué es importante

La REST API de WordPress es la interfaz que permite que tu sitio se comunique con aplicaciones externas y con el propio panel de administración mediante peticiones HTTP. A través de la ruta /wp-json/, WordPress expone datos y funcionalidades en formato JSON, lo que hace posible que editores de bloques, aplicaciones móviles, constructores visuales y servicios de terceros interactúen con tu web sin necesidad de cargar todo el entorno de administración.

Desde la llegada del editor de bloques (Gutenberg), la REST API se ha vuelto crítica para el funcionamiento normal del panel. Si la API falla, muchas tareas cotidianas dejan de funcionar correctamente: guardar entradas, previsualizar cambios, gestionar menús o incluso instalar plugins. Por eso, cuando aparece el mensaje de "Error de REST API" en la herramienta de Salud del sitio, conviene actuar de inmediato.

Síntomas habituales del error de REST API en WordPress

El error de REST API puede manifestarse de varias formas. A veces aparece un mensaje claro en el panel de administración, pero en otras ocasiones solo se perciben comportamientos extraños. Identificar estos síntomas ayuda a confirmar que el problema está relacionado con la API y no con otro componente del sitio.

• Mensaje de advertencia en Herramientas > Salud del sitio indicando: "La REST API encontró un error" o "La REST API está bloqueada".
• Problemas al usar el editor de bloques: errores al guardar, mensajes de "La respuesta no es una respuesta JSON válida" o bloqueos al actualizar entradas y páginas.
• Imposibilidad de previsualizar cambios en tiempo real o de cargar ciertos paneles del editor que dependen de peticiones AJAX/REST.
• Errores 404, 401, 403 o 500 al acceder directamente a https://tusitio.com/wp-json/ o a rutas específicas de la API.
• Widgets o bloques que muestran datos externos dejan de actualizarse o muestran mensajes de error genéricos.
• Aplicaciones móviles de WordPress o integraciones externas (por ejemplo, formularios, CRMs, herramientas de automatización) dejan de sincronizarse.

Causas más comunes del error de REST API

El error de REST API en WordPress suele deberse a una combinación de factores relacionados con el servidor, la configuración de seguridad y el propio código del sitio. Conocer las causas más habituales permite acotar el problema con rapidez y aplicar la solución adecuada sin realizar cambios innecesarios.

• Reglas de seguridad o firewall demasiado restrictivas: plugins de seguridad, firewalls a nivel de servidor o servicios CDN/WAF (como Cloudflare) que bloquean las rutas /wp-json/ o métodos HTTP como POST y PUT.
• Configuración incorrecta de .htaccess o Nginx: reglas de reescritura mal definidas, redirecciones en bucle o bloqueos por IP/User-Agent que afectan a las peticiones de la API.
• Plugins o temas mal programados: código que engancha filtros de la REST API, modifica cabeceras o genera errores PHP que rompen la respuesta JSON.
• Problemas de HTTPS y certificados SSL: certificados caducados, mal instalados o configuraciones mixtas de HTTP/HTTPS que impiden que el navegador o el servidor confíen en las peticiones.
• Configuración de caché agresiva: plugins de caché o proxies que almacenan en caché respuestas dinámicas de la API, devuelven HTML en lugar de JSON o sirven contenido obsoleto.
• Restricciones de CORS o cabeceras mal definidas: cuando la API se consume desde otro dominio, las políticas de origen cruzado pueden bloquear las peticiones si las cabeceras no están bien configuradas.
• Errores de permisos o autenticación: usuarios sin los privilegios necesarios, tokens caducados o métodos de autenticación incompatibles con la configuración actual del sitio.
• Límites del servidor: restricciones de recursos (memoria, tiempo de ejecución, módulos de PHP desactivados) que provocan errores 500 o respuestas incompletas.

Cómo diagnosticar el error de REST API paso a paso

Un diagnóstico ordenado evita perder tiempo probando soluciones al azar. El objetivo es aislar el origen del problema: saber si viene del servidor, de un plugin, del tema o de una configuración externa como un firewall o CDN. A continuación se detalla un flujo de trabajo recomendado para localizar la causa del error de REST API en WordPress.

• 1. Comprobar la herramienta de Salud del sitio
  Ve a Herramientas > Salud del sitio > Estado y revisa el apartado de REST API. Anota el mensaje exacto que aparece y, si es posible, copia los detalles adicionales. Esto te dará pistas sobre si el problema es de conectividad, autenticación o respuesta inválida.
• 2. Probar la ruta /wp-json/ directamente
  Accede en tu navegador a https://tusitio.com/wp-json/. Deberías ver un documento JSON legible. Si obtienes un error 404, 500, 401 o una página HTML, ya tienes una pista importante sobre el tipo de bloqueo.
• 3. Activar el modo de depuración de WordPress
  Edita el archivo wp-config.php y activa las constantes de depuración:

  define( 'WP_DEBUG', true );
  define( 'WP_DEBUG_LOG', true );
  define( 'WP_DEBUG_DISPLAY', false );

  Después, vuelve a probar la REST API y revisa el archivo wp-content/debug.log en busca de errores PHP.
• 4. Desactivar todos los plugins temporalmente
  Desactiva todos los plugins desde el panel o renombra la carpeta wp-content/plugins. Vuelve a probar la ruta /wp-json/. Si la API funciona, reactiva los plugins uno a uno hasta encontrar el que causa el conflicto.
• 5. Cambiar al tema por defecto
  Activa un tema oficial reciente (por ejemplo, Twenty Twenty-Four). Si el problema desaparece, el error está en el tema actual o en funciones personalizadas que interfieren con la REST API.
• 6. Probar sin CDN ni firewall externo
  Si usas Cloudflare u otro CDN/WAF, pon el sitio en modo "Desarrollo" o desactiva temporalmente el proxy. Comprueba de nuevo la API para descartar bloqueos externos.
• 7. Revisar los registros del servidor
  Accede al panel de tu hosting y revisa los logs de errores de Apache/Nginx y PHP. Busca entradas relacionadas con peticiones a /wp-json/ o errores 500 que coincidan con tus pruebas.

Soluciones básicas para el error de REST API

Una vez identificadas las posibles causas, puedes aplicar una serie de soluciones estándar que resuelven la mayoría de errores de REST API en WordPress. Es recomendable probarlas en un entorno de pruebas o con una copia de seguridad reciente, especialmente si vas a modificar archivos de configuración o desactivar plugins críticos.

• Regenerar los enlaces permanentes
  Ve a Ajustes > Enlaces permanentes y haz clic en "Guardar cambios" sin modificar nada. Esto fuerza a WordPress a regenerar las reglas de reescritura, lo que puede solucionar errores 404 en /wp-json/.
• Actualizar WordPress, temas y plugins
  Asegúrate de que estás usando la última versión estable de WordPress y de tus extensiones. Muchas incompatibilidades con la REST API se corrigen en actualizaciones.
• Desactivar plugins de seguridad y caché
  Desactiva temporalmente plugins como Wordfence, iThemes Security, Sucuri, así como plugins de caché (W3 Total Cache, WP Rocket, LiteSpeed Cache, etc.). Si la API vuelve a funcionar, revisa sus ajustes de firewall y exclusiones.
• Revisar funciones personalizadas
  Si has añadido código en functions.php o en un plugin propio, comenta temporalmente cualquier función relacionada con la REST API o que modifique cabeceras y respuestas.
• Comprobar la URL del sitio
  En Ajustes > Generales, verifica que las URLs de "Dirección de WordPress" y "Dirección del sitio" son correctas y usan el mismo protocolo (HTTP o HTTPS). Inconsistencias aquí pueden provocar errores de ruta y redirecciones.
• Eliminar reglas personalizadas conflictivas
  Si has añadido reglas específicas en .htaccess o en la configuración de Nginx, coméntalas temporalmente para ver si la API se restablece.

Revisión de configuración del servidor y .htaccess

Muchos errores de REST API se originan en la capa del servidor web. Reglas de reescritura incorrectas, módulos desactivados o directivas de seguridad mal configuradas pueden impedir que las peticiones a /wp-json/ lleguen correctamente a WordPress. Ajustar la configuración de Apache, Nginx o el archivo .htaccess suele ser clave para restaurar la API.

Configuración recomendada de .htaccess para WordPress

En instalaciones típicas con Apache, el archivo .htaccess en la raíz de WordPress debería contener, como mínimo, las reglas estándar de reescritura. Un ejemplo básico es el siguiente:

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

Si tu archivo contiene reglas adicionales, especialmente las que afectan a /wp-json/, wp-admin o métodos HTTP, revísalas con cuidado. Cualquier directiva que bloquee GET, POST o cabeceras específicas puede interferir con la REST API.

Consideraciones para Nginx

En servidores Nginx, la configuración se define en bloques server. Asegúrate de que las reglas de reescritura apuntan correctamente a index.php y que no hay ubicaciones (location) que bloqueen /wp-json/ o devuelvan respuestas estáticas en su lugar.

• Comprueba que no exista un bloque location /wp-json que devuelva un 403 o 404.
• Verifica que las reglas de caché no se apliquen de forma agresiva a rutas de la API.
• Confirma que PHP-FPM está correctamente enlazado y que no hay errores de tiempo de espera.

Módulos y límites de PHP

La REST API depende de que PHP pueda ejecutar las peticiones sin interrupciones. Si los límites son demasiado bajos o faltan módulos esenciales, las respuestas pueden cortarse o devolver errores 500.

• Aumenta memory_limit y max_execution_time si el sitio es grande o tiene muchos plugins.
• Asegúrate de que extensiones como curl, json y mbstring están activas.
• Revisa los logs de PHP para detectar errores fatales durante las peticiones a /wp-json/.

Plugins de seguridad, firewall y caché: ajustes recomendados

Los plugins de seguridad y caché son una de las causas más frecuentes de errores en la REST API, porque filtran, bloquean o modifican las peticiones HTTP. Configurarlos correctamente es esencial para mantener el equilibrio entre protección y funcionalidad.

Plugins de seguridad y firewall

Herramientas como Wordfence, iThemes Security, Sucuri o All In One WP Security pueden bloquear rutas sensibles por defecto. Aunque esto mejora la seguridad, también puede afectar a la REST API si no se ajustan las reglas.

• Revisa las opciones relacionadas con la protección de la REST API o bloqueo de XML-RPC y API.
• Añade /wp-json/ a las listas de exclusión cuando el plugin lo permita.
• Desactiva temporalmente reglas avanzadas de firewall para comprobar si son la causa del error.
• Si usas listas de bloqueo por IP o país, verifica que tu propia IP y los servicios que consumen la API no estén bloqueados.

Plugins de caché y optimización

Los sistemas de caché pueden intentar almacenar en caché las respuestas de la REST API, lo que genera inconsistencias y respuestas inválidas. Para evitarlo, es recomendable excluir las rutas de la API de la caché.

• Configura reglas para no cachear las URLs que comiencen por /wp-json/.
• Desactiva la minificación o combinación de JavaScript si notas errores en el editor de bloques tras su activación.
• Vacía la caché completa del sitio y del navegador después de realizar cambios en la configuración.
• Si usas un proxy inverso (como Varnish), asegúrate de que respeta las cabeceras de no caché de la API.

CDN y WAF externos

Servicios como Cloudflare, Sucuri Firewall o Imperva añaden una capa adicional de seguridad y caché. Si no se configuran correctamente, pueden bloquear o modificar las peticiones a la REST API.

• Activa el modo desarrollo o desactiva temporalmente el proxy para descartar su influencia.
• Crea reglas de firewall que permitan explícitamente el acceso a /wp-json/.
• Excluye la ruta de la API de la caché a nivel de CDN.
• Revisa los registros de eventos de seguridad para ver si las peticiones a la API están siendo bloqueadas.

REST API, HTTPS, CORS y cabeceras

Cuando la REST API de WordPress se consume desde otros dominios o aplicaciones externas, entran en juego factores adicionales como el cifrado HTTPS, las políticas CORS y las cabeceras HTTP. Una configuración incorrecta en cualquiera de estos puntos puede provocar errores aparentemente inexplicables, incluso si el sitio carga con normalidad en el navegador.

Certificados SSL y HTTPS

Si tu sitio usa HTTPS, la REST API también debe ser accesible a través de HTTPS sin advertencias de seguridad. Problemas con el certificado pueden hacer que navegadores y clientes HTTP rechacen las peticiones.

• Comprueba que el certificado SSL no está caducado y está correctamente instalado.
• Evita redirecciones en bucle entre HTTP y HTTPS que afecten a /wp-json/.
• Verifica que las URLs del sitio en WordPress usan siempre HTTPS si el dominio está configurado así.

CORS (Cross-Origin Resource Sharing)

Si una aplicación externa en otro dominio intenta consumir tu REST API, el navegador aplicará las políticas CORS. Si el servidor no envía las cabeceras adecuadas, las peticiones serán bloqueadas por el navegador, aunque el servidor responda correctamente.

• Añade cabeceras Access-Control-Allow-Origin adecuadas en el servidor o mediante código en WordPress.
• Permite los métodos HTTP necesarios (GET, POST, PUT, DELETE) en Access-Control-Allow-Methods.
• Incluye cabeceras personalizadas en Access-Control-Allow-Headers si tu aplicación las utiliza.

Cabeceras y tipo de contenido

La REST API debe devolver respuestas en formato JSON con el tipo de contenido correcto. Si algún plugin o código personalizado modifica las cabeceras o inyecta HTML, la respuesta dejará de ser válida y el editor de bloques mostrará errores.

• Comprueba que la respuesta de /wp-json/ comienza con JSON válido y no contiene HTML adicional.
• Evita imprimir mensajes de depuración o avisos directamente en la salida cuando la API está en uso.
• Usa funciones de WordPress para registrar rutas y respuestas de la API en lugar de generar salida manualmente.

Buenas prácticas para prevenir errores de REST API

Más allá de solucionar un error concreto, es importante adoptar una serie de buenas prácticas que reduzcan la probabilidad de que la REST API vuelva a fallar en el futuro. Esto es especialmente relevante en sitios complejos, con muchos plugins o integraciones externas que dependen de la API para funcionar correctamente.

• Mantener WordPress y extensiones actualizados
  Actualiza con regularidad el núcleo de WordPress, los temas y los plugins. Las versiones recientes suelen incluir mejoras de compatibilidad y correcciones de seguridad relacionadas con la REST API.
• Limitar el número de plugins
  Evita instalar plugins redundantes o de baja calidad. Cada plugin adicional aumenta la superficie de conflicto potencial con la API.
• Revisar el código personalizado
  Si desarrollas funciones propias, sigue las buenas prácticas de la API de WordPress, usa los hooks oficiales y evita modificar cabeceras o salidas globales sin necesidad.
• Configurar correctamente la seguridad
  En lugar de bloquear la REST API por completo, aplica reglas específicas que limiten el acceso solo a rutas sensibles o a métodos que realmente deban protegerse.
• Monitorizar la Salud del sitio
  Revisa periódicamente la herramienta de Salud del sitio para detectar advertencias tempranas sobre la REST API y otros componentes críticos.
• Probar cambios en un entorno de staging
  Antes de aplicar cambios importantes en producción (nuevos plugins, cambios de servidor, ajustes de firewall), pruébalos en un entorno de pruebas para detectar posibles impactos en la API.
• Documentar la configuración
  Mantén un registro de las reglas de firewall, exclusiones de caché y ajustes de servidor que afectan a la REST API. Esto facilita la resolución de incidencias futuras.

Preguntas frecuentes sobre el error de REST API en WordPress