La API REST de WordPress devuelve 404

Qué significa este error y cómo reconocerlo

• Al abrir /wp-json/ aparece una página de error HTTP 404 en lugar del JSON del índice de la API REST.
• Una aplicación JavaScript, aplicación móvil, cliente REST, editor o integración informa de 404 Not Found para una solicitud a la API de WordPress.
• El frontend de WordPress carga con normalidad mientras fallan las solicitudes REST.
• ?rest_route=/ funciona aunque la ruta amigable /wp-json/ devuelva 404.
• El índice de la API carga, pero un plugin o endpoint personalizado devuelve 404.
• Salud del sitio de WordPress informa de que la API REST no está disponible; aun así, es necesario comprobar el cuerpo de la respuesta y el código de estado para identificar el origen.

Causas principales, ordenadas por probabilidad

1. Reglas de reescritura de enlaces permanentes desactualizadas o ausentes. Es habitual después de una migración, un cambio de enlaces permanentes, un cambio de servidor o un despliegue incompleto.
2. El servidor web o el proxy no dirige /wp-json/ a WordPress. La compatibilidad con reescrituras de Apache, el enrutamiento try_files de Nginx, la asignación de la raíz del documento o la configuración del host virtual pueden ser incorrectos.
3. Una regla de seguridad, firewall, CDN, caché o hosting devuelve 404. Algunos controles ocultan las solicitudes bloqueadas devolviendo no encontrado en lugar de prohibido.
4. Un plugin o tema modifica el comportamiento de REST. Puede eliminar rutas, restringir el acceso o filtrar las respuestas REST.
5. Solo una ruta personalizada o de un plugin es incorrecta. La solicitud puede tener un namespace, ruta, versión, método HTTP o ID de recurso incorrectos, o la ruta puede no estar registrada.
6. La solicitud apunta a la instalación o al sitio equivocados. Los cambios de dominio, las instalaciones en subdirectorios, las redirecciones, los ajustes obsoletos de la aplicación y las respuestas almacenadas en caché pueden hacer que los clientes usen una ruta base de la API desactualizada.

Cómo solucionarlo

1. Confirma el alcance y el origen del 404

Registra la ruta exacta de la solicitud, el estado HTTP, el cuerpo de la respuesta, las cabeceras de respuesta, el método de solicitud y la marca de tiempo. Comprueba si la respuesta parece proceder de WordPress, del servidor web, de un proxy inverso, de una CDN o de una capa de seguridad. No incluyas tokens de acceso, cookies, contraseñas ni datos privados de la respuesta en los registros de diagnóstico.

Prueba el índice de la API REST en /wp-json/ desde un cliente adecuado. Si el índice devuelve JSON pero un endpoint devuelve 404, pasa directamente al paso 5. Si el propio índice devuelve 404, continúa.

2. Actualiza las reglas de reescritura de WordPress

En el panel de WordPress, abre Ajustes → Enlaces permanentes y haz clic en Guardar cambios sin cambiar la estructura de enlaces permanentes seleccionada. Esto actualiza la configuración de reescritura de WordPress.

Vuelve a probar /wp-json/. Si la automatización de despliegues o el panel de control del hosting gestiona la configuración del servidor, confirma que los ajustes de reescritura se conservan y que el siguiente despliegue no los sobrescribe.

3. Compara la ruta amigable con la ruta alternativa

Prueba la API REST usando la alternativa de WordPress mediante parámetro de consulta: ?rest_route=/, añadido a la dirección de inicio normal del sitio. Usa el esquema, el hostname y la ruta de instalación reales. Una instalación en un subdirectorio puede requerir que esa ruta siga formando parte de la solicitud.

• La alternativa funciona pero /wp-json/ falla: WordPress puede procesar las solicitudes REST, así que investiga las reescrituras de URL amigables, la configuración del host virtual, el enrutamiento del proxy, la asignación de la raíz del documento y los cambios de la migración.
• Ambas fallan: revisa los controles de seguridad, el enrutamiento del front controller del servidor, el comportamiento de WordPress y los plugins, y la ruta configurada del sitio o de la instalación.
• Ambas solicitudes al índice funcionan pero falla una ruta personalizada: diagnostica específicamente ese endpoint en el paso 5.

4. Comprueba el enrutamiento del servidor web, el proxy y la seguridad

En Apache, solicita a un administrador autorizado que verifique que la compatibilidad con reescrituras está habilitada para el directorio de WordPress y que las reglas de reescritura del sitio están presentes y permitidas por la configuración del host virtual. En Nginx o en un proxy inverso, verifica que las solicitudes llegan al front controller de WordPress y que /wp-json/ no se trata como un archivo estático ausente.

Revisa los registros pertinentes en este orden:

1. Registros de acceso y errores del servidor web para la solicitud fallida.
2. Reglas y entradas de caché de la CDN, el balanceador de carga y el proxy inverso.
3. Plugins de seguridad, firewall, protección de inicio de sesión y control REST de WordPress.
4. Reglas del WAF del hosting que puedan clasificar la ruta, el método o las cabeceras de la solicitud como bloqueados.

Haz un cambio controlado cada vez, registra el ajuste original y purga únicamente la caché pertinente después de obtener autorización. No deshabilites ampliamente un firewall de producción ni un plugin de seguridad sin un plan de mantenimiento aprobado. Si una regla de seguridad es la responsable, permite de forma limitada la ruta y los métodos REST necesarios en lugar de omitir toda la protección.

5. Diagnostica un endpoint concreto que falta

Confirma el namespace exacto del endpoint, la ruta, el segmento de versión, el método HTTP, la ruta final y el identificador del recurso. Compara la solicitud con la documentación de la ruta o con el código de registro proporcionado por el plugin o la aplicación.

Verifica que:

• El plugin o tema responsable está activo en el entorno que se está probando.
• El registro de la ruta se ejecuta durante la inicialización de REST.
• La ruta tiene la función de comprobación de permisos esperada y no se omite condicionalmente para la solicitud actual.
• El cliente usa la ruta base de la API del sitio actual en lugar de un dominio, subdirectorio o ajuste de la aplicación almacenado en caché y obsoleto.
• El recurso solicitado existe realmente. La ausencia de una entrada, usuario, producto u otro recurso puede producir un 404 legítimo a nivel del endpoint aunque la API REST funcione correctamente.

Comprueba el índice de la API o la respuesta de descubrimiento de rutas cuando esté disponible. Si la ruta esperada no aparece, investiga el registro, el estado del plugin, el namespace y la configuración específica del entorno en lugar de tratar el problema como una caída general de REST.

6. Vuelve a comprobar después de cada cambio controlado

Vuelve a probar desde un navegador, un cliente API autorizado y, cuando corresponda, la aplicación que informó del error. Compara el código de estado, las cabeceras de respuesta, el cuerpo de la respuesta y el origen de la respuesta antes y después de cada cambio. Revierte los cambios temporales de diagnóstico y documenta la configuración final de reescritura, firewall, caché, proxy o plugin.

Prevención y cómo verificar la solución

• Añade una prueba de funcionamiento de la API REST para /wp-json/ y para cada ruta personalizada crítica para el negocio a las comprobaciones de migración y despliegue.
• Mantén coherentes entre entornos la URL del sitio de WordPress, la URL de inicio, la raíz del documento y la configuración del subdirectorio.
• Gestiona la configuración de reescritura, las reglas del proxy, las políticas del firewall y el comportamiento de la caché como ajustes de despliegue documentados, no como cambios de servidor sin documentar.
• Revisa los cambios de los plugins de seguridad y del WAF para detectar efectos tanto en las solicitudes REST autenticadas como en las no autenticadas.
• Supervisa el estado y el origen de la respuesta de las llamadas API importantes para distinguir un 404 generado por un proxy de uno generado por WordPress.
• Documenta los namespaces personalizados, las rutas, los métodos compatibles, el comportamiento de los permisos y el plugin o tema responsable de cada endpoint.