Как исправить 404 и permission error в WordPress REST API

Если в админке или на фронтенде что-то завязано на REST API, ошибка 404 или permission error обычно ломает не одну мелочь, а сразу несколько сценариев: автосохранение в редакторе, загрузку данных в блоках, работу мобильных приложений, интеграции с внешними сервисами. В WordPress это не всегда проблема самого API — часто виноваты правила сервера, плагины безопасности, кастомные ограничения или конфликт в теме.

Ниже — практический разбор: как понять, где именно ломается запрос, что проверить в первую очередь и как безопасно исправить проблему без отключения всего сайта.

Как выглядит проблема на практике

Типовые симптомы разные, но сводятся к нескольким сценариям:

• в браузере по адресу /wp-json/ открывается 404;
• в консоли редактора появляется ошибка Updating failed. The response is not a valid JSON response;
• в ответе API приходит rest_forbidden или permission error;
• часть эндпоинтов работает, а часть — нет;
• запросы к /wp-json/wp/v2/posts возвращают HTML вместо JSON.

Важно не путать две разные ситуации: API действительно недоступен на уровне маршрутизации и API доступен, но WordPress запрещает доступ по правам или по логике плагина. Лечение у этих случаев разное.

Диагностика: что проверить до правок в коде

Начинать лучше не с правки functions.php, а с проверки самого запроса. Это экономит время и помогает не сломать рабочую часть сайта.

1. Откройте базовый endpoint вручную

Проверьте в браузере адрес https://ваш-домен.ru/wp-json/. Нормальный ответ — JSON с информацией о маршрутах. Если вместо этого 404, ищите проблему в сервере, кэше или правилах перезаписи.

2. Посмотрите ответ в DevTools

Откройте вкладку Network и найдите запрос к REST endpoint. Важно увидеть:

• код ответа;
• реальный URL;
• тип ответа — JSON или HTML;
• нет ли редиректа на страницу входа, 403 или 500.

Если запрос уходит на http вместо https, или домен отличается от основного, проблема может быть в настройках siteurl/home или в прокси.

3. Временно отключите плагины безопасности и кэширования

Чаще всего REST API ломают плагины, которые фильтруют запросы по User-Agent, блокируют /wp-json/ или режут доступ для неавторизованных пользователей. Для проверки достаточно временно отключить:

• security-плагины;
• кэш-плагины;
• плагины редиректов и антиспама;
• кастомные MU-плагины.

Если после отключения проблема исчезла, не возвращайте всё как было сразу. Включайте по одному и фиксируйте, на каком именно плагине ломается ответ.

Почему REST API возвращает 404

404 обычно означает, что запрос не дошёл до WordPress как до приложения. Чаще всего причина в правилах сервера или в некорректной обработке ЧПУ.

Проверьте постоянные ссылки и правила перезаписи

Если /wp-json/ отдаёт 404, сначала зайдите в Настройки → Постоянные ссылки и просто сохраните их без изменений. Это пересоздаёт правила rewrite. На Apache это часто достаточно, если .htaccess не повреждён.

Для Nginx проверьте, что конфигурация действительно передаёт несуществующие файлы в index.php. Базовый фрагмент обычно выглядит так:

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

Если этого нет, WordPress не сможет обработать маршрут /wp-json/, и запрос уйдёт в 404 на уровне веб-сервера.

Проверьте, не режет ли путь прокси или WAF

Иногда REST API блокирует внешний слой: Cloudflare, ModSecurity, nginx rules, хостинговый WAF. В логах при этом может быть пусто, а в браузере — 403 или 404. Если сайт за прокси, проверьте, не переписывается ли путь /wp-json/ в отдельное правило блокировки.

Почему появляется permission error

Если endpoint открывается, но WordPress отвечает отказом, значит маршрут найден, но доступ к нему ограничен. Это уже не проблема rewrite, а вопрос прав, nonce или логики плагина.

Проверьте авторизацию и nonce

Для запросов из админки WordPress использует nonce. Если он устарел, запросы на запись могут падать с ошибкой доступа. Это особенно заметно после долгой неактивности вкладки или при агрессивном кэшировании HTML.

Если вы делаете кастомный AJAX/REST-запрос, передавайте nonce корректно и проверяйте его на сервере. Пример регистрации собственного маршрута:

add_action('rest_api_init', function () {
    register_rest_route('myplugin/v1', '/ping', array(
        'methods'  => 'GET',
        'callback' => 'myplugin_rest_ping',
        'permission_callback' => '__return_true',
    ));
});

function myplugin_rest_ping(WP_REST_Request $request) {
    return rest_ensure_response(array(
        'ok' => true,
        'time' => current_time('mysql'),
    ));
}

Если endpoint должен быть доступен только авторизованным пользователям, вместо __return_true используйте явную проверку:

function myplugin_can_manage_rest() {
    return current_user_can('edit_posts');
}

add_action('rest_api_init', function () {
    register_rest_route('myplugin/v1', '/secure-data', array(
        'methods'  => 'GET',
        'callback' => 'myplugin_secure_data',
        'permission_callback' => 'myplugin_can_manage_rest',
    ));
});

Проверьте, не переопределяет ли доступ плагин

Некоторые плагины безопасности ограничивают REST API глобально или для гостей. Это нормально, если сайт не использует публичные endpoint'ы. Но если у вас редактор, headless-часть или внешняя интеграция, такое ограничение будет ломать функциональность.

Вместо полного отключения защиты лучше найти конкретную настройку: whitelist для /wp-json/, исключение для нужного endpoint'а или разрешение только для авторизованных пользователей.

Пошаговое решение без лишнего риска

1. Проверьте /wp-json/ в браузере и в Network.
2. Сохраните постоянные ссылки заново.
3. Отключите плагины безопасности, кэша и редиректов.
4. Проверьте .htaccess или конфигурацию Nginx.
5. Сравните ответ на чистой теме и на текущей теме.
6. Если ошибка только в одном кастомном endpoint, проверьте permission_callback и логику проверки прав.

Если проблема в теме, ищите код, который вмешивается в REST API через фильтры или отключает маршруты. Иногда достаточно одного неаккуратного фрагмента в functions.php.

Как быстро проверить, что исправление сработало

После правок не ограничивайтесь визуальной проверкой в админке. Нужна проверка ответа API.

• Откройте /wp-json/ и убедитесь, что приходит JSON, а не 404;
• проверьте конкретный маршрут, который ломался раньше;
• в редакторе создайте/обновите запись и посмотрите, ушла ли ошибка сохранения;
• в DevTools убедитесь, что код ответа 200, а не 403/404/500;
• если был nonce error, обновите страницу и повторите запрос после новой загрузки.

Для быстрой проверки с сервера удобно использовать curl:

curl -I https://example.com/wp-json/

Если ответ идёт с редиректом, 403 или 404, проблема ещё не закрыта. Если приходит корректный JSON-ответ, значит маршрут доступен на уровне сервера и WordPress.

Частые ошибки и как их исправить

Кэш отдает старый HTML вместо JSON

Это бывает, когда кэш-плагин или CDN кеширует ответ API как обычную страницу. Для REST API такие ответы нужно исключать из кэша. Иначе WordPress будет получать не JSON, а старую HTML-страницу, и редактор начнёт ругаться на формат ответа.

В теме или плагине отключили REST API целиком

Иногда разработчики добавляют жёсткое ограничение вроде блокировки всех неавторизованных запросов. Это ломает не только внешние интеграции, но и часть штатного функционала WordPress. Если ограничение нужно, делайте его точечно — только для конкретных маршрутов.

Неверный permission_callback

Если callback всегда возвращает false или проверяет не ту capability, endpoint будет недоступен даже администратору. Для публичных данных используйте __return_true, для закрытых — явную проверку прав.

Сломаны правила перезаписи после миграции

После переноса сайта на другой сервер или домен rewrite-правила могут не совпасть с текущей конфигурацией. В этом случае сохранение постоянных ссылок часто помогает, но если нет — смотрите конфиг веб-сервера и логи.

Практика безопасности и производительности

REST API не стоит отключать «на всякий случай». Это часто приводит к побочным поломкам в редакторе и интеграциях. Лучше ограничивать доступ точечно и понимать, что именно вы закрываете.

Если сайт публичный, оставляйте доступными только те маршруты, которые реально нужны. Если у вас есть кастомные endpoint'ы, не возвращайте из них тяжёлые запросы без необходимости. Для сложных выборок лучше кэшировать результат на короткое время через transient, но только если данные не должны быть мгновенно актуальными.

Если вам нужно регулярно чистить сайт от дублей, мусора и технических хвостов, полезно посмотреть в сторону инструментов вроде Clearfy Pro: он не чинит REST API напрямую, но помогает убрать лишние SEO-дубли и часть технических настроек, которые часто мешают диагностике. Подробности есть на странице плагина.

Если после всех проверок ошибка остаётся только на одном endpoint'е, проблема почти наверняка в его регистрации или в проверке прав. Если же ломается весь /wp-json/, начинайте с сервера, rewrite и кэша — это самые частые причины.