Jak skutecznie rozwiązać problemy z REST API w WordPress?

REST API w WordPress to wbudowany interfejs, który pozwala komunikować się z witryną przez protokół HTTP, używając danych w formacie JSON. Dostępny jest pod adresem `https://twojadomena.pl/wp-json/` i od wersji WordPress 4.7 stanowi rdzeń systemu – nie da się go całkowicie usunąć bez psucia panelu.

Do czego konkretnie służy REST API:

• Edytor blokowy Gutenberg – każde zapisanie wpisu, dodanie bloku czy autosave odbywa się przez wywołania do `/wp-json/wp/v2/`.
• Architektura headless – frontend zbudowany w Next.js, Astro czy React pobiera treści z WordPressa właśnie przez REST API.
• Integracje zewnętrzne – aplikacje mobilne, CRM, narzędzia marketing automation i wtyczki łączące się z WooCommerce.
• Funkcje panelu – Stan witryny, podgląd na żywo w Personalizacji, wiele paneli wtyczek.

Każde żądanie zawiera nagłówki podstawowe, takie jak `Content-Type: application/json`, a przy operacjach wymagających logowania także nagłówek autoryzacyjny lub nonce. Gdy REST API jest zablokowane, najczęstszym objawem jest komunikat Aktualizacja nie powiodła się lub Publikacja nie powiodła się w edytorze – to klasyczny sygnał, że żądania do `wp-json` nie docierają.

Zanim zaczniesz cokolwiek naprawiać, ustal, czy problem faktycznie dotyczy REST API. Masz do dyspozycji dwie szybkie metody.

Test endpointu przez przeglądarkę

Wpisz w pasku adresu `https://twojadomena.pl/wp-json/`. Prawidłowa odpowiedź to obszerny dokument JSON z nazwą witryny, opisem i listą dostępnych namespace'ów (np. `wp/v2`, `oembed/1.0`). Jeśli zamiast tego widzisz stronę 404, pustą biel albo komunikat o błędzie serwera – masz potwierdzenie problemu.

Możesz też sprawdzić konkretny endpoint publiczny: `https://twojadomena.pl/wp-json/wp/v2/posts` powinien zwrócić listę najnowszych wpisów w formacie JSON.

Narzędzie Stan witryny (Site Health)

W panelu przejdź do Narzędzia → Stan witryny → Status. WordPress automatycznie testuje dostępność REST API i jeśli wykryje blokadę, wyświetli czerwony komunikat Interfejs REST API napotkał błąd wraz z kodem HTTP. To najszybszy sposób, by od razu poznać typ błędu (401, 403, 404, 500) bez ręcznego klikania po endpointach.

Jeśli oba testy przechodzą poprawnie, a edytor nadal nie zapisuje treści, przyczyna może leżeć po stronie cache przeglądarki lub wygasłego nonce – do tego wrócimy niżej.

Kod HTTP zwracany przez `wp-json` precyzyjnie wskazuje kierunek diagnozy. Oto najczęstsze błędy:

• 401 Unauthorized – brak lub nieprawidłowe uwierzytelnienie. Pojawia się, gdy nonce wygasł (żyje ok. 24 godziny i koliduje z agresywnym cache) albo gdy próbujesz sięgnąć po endpoint chroniony bez ważnych danych logowania lub Application Password.
• 403 Forbidden – serwer lub wtyczka świadomie blokuje dostęp. Najczęstszy sprawca to wtyczka bezpieczeństwa (Wordfence, Solid Security) lub reguła ModSecurity/WAF na hostingu, która uznaje żądanie za podejrzane.
• 404 Not Found – WordPress nie potrafi dopasować trasy `/wp-json/`. Zwykle wynika to z błędnych ustawień bezpośrednich odnośników (permalinks) lub uszkodzonego `.htaccess`. To najczęstsza przyczyna problemów po migracji witryny.
• 500 Internal Server Error – błąd po stronie PHP: konflikt wtyczek, błąd w kodzie motywu, przekroczony limit pamięci. Tu konieczne jest zajrzenie do logów PHP.
• 503 Service Unavailable – serwer chwilowo niedostępny, najczęściej podczas aktualizacji (tryb konserwacji) lub przy przeciążeniu zasobów na współdzielonym hostingu.

Zanotuj dokładny kod – to on zdecyduje, którą z poniższych sekcji zastosujesz w pierwszej kolejności.

Te trzy przyczyny odpowiadają za większość zgłoszeń, dlatego warto je wykluczyć w pierwszej kolejności.

Konflikt wtyczek (diagnoza metodą połowienia)

Najskuteczniejszy sposób to dezaktywacja wszystkich wtyczek naraz, a następnie włączanie ich pojedynczo:

1. Przejdź do Wtyczki → Zainstalowane wtyczki, zaznacz wszystkie i wybierz Wyłącz.
2. Sprawdź, czy `wp-json` znów odpowiada poprawnie.
3. Jeśli tak – włączaj wtyczki po jednej, za każdym razem testując endpoint.
4. Wtyczka, po której błąd wraca, jest winowajcą.

Najczęściej konflikt powodują wtyczki bezpieczeństwa, cache oraz starsze rozszerzenia SEO. Jeśli nie masz dostępu do panelu, zmień nazwę folderu `/wp-content/plugins/` przez FTP lub menedżer plików, by wyłączyć wszystkie wtyczki naraz.

Błędne ustawienia bezpośrednich odnośników (permalinks)

Błąd 404 na `/wp-json/` często znika po prostym odświeżeniu reguł przepisywania. Wejdź w Ustawienia → Bezpośrednie odnośniki i bez żadnych zmian kliknij Zapisz zmiany. WordPress wygeneruje na nowo reguły rewrite i często to wystarcza.

Problemy z plikiem .htaccess (Apache vs Nginx)

Na serwerach Apache reguły przepisywania zapisane są w pliku `.htaccess` w katalogu głównym. Jeśli plik został uszkodzony, usuń jego zawartość między znacznikami `# BEGIN WordPress` i `# END WordPress`, a następnie odśwież permalinki – WordPress odtworzy poprawne reguły.

Wiele polskich hostingów (cyberFolks, LH.pl, Zenbox) używa jednak Nginx lub LiteSpeed, gdzie plik .htaccess nie działa lub działa inaczej. Na Nginx reguły przepisywania konfiguruje się po stronie serwera, więc gdy permalinki nie działają, problem leży w konfiguracji vhosta – wtedy konieczny jest kontakt z hostingiem lub panel, który tym zarządza (np. zmiana środowiska na obsługujące WordPress).

Gdy podstawowa diagnostyka nie pomogła, sprawcą jest zwykle warstwa bezpieczeństwa lub buforowania.

Wtyczki bezpieczeństwa blokujące wp-json

Wordfence i Solid Security (dawniej iThemes Security) mają opcje ograniczania dostępu do REST API. To dobre dla bezpieczeństwa, ale potrafi zablokować legalne żądania:

• W Wordfence sprawdź Firewall → Blocking oraz reguły rate limiting i dodaj wyjątek dla ścieżki `/wp-json/`.
• W Solid Security wyłącz tymczasowo opcję Filter Suspicious Query Strings i restrykcje REST API, by ustalić, czy to one blokują.
• Po znalezieniu winnej reguły dodaj wyjątek zamiast całkowicie wyłączać ochronę.

Cache jako przyczyna

Wtyczki cache (W3 Total Cache, WP Rocket) oraz cache na poziomie Cloudflare mogą buforować odpowiedzi REST API i nonce. Efekt to błędy 401 przy zapisie wpisów. Wyklucz ścieżkę `/wp-json/` z buforowania w ustawieniach wtyczki, a w Cloudflare upewnij się, że reguły Cache Rules nie obejmują tej ścieżki. Po zmianach wyczyść cały cache.

Uwierzytelnianie do endpointów niepublicznych

Endpointy publiczne (np. lista wpisów) działają bez logowania, ale operacje zapisu wymagają uwierzytelnienia:

• Nonce – używany w panelu, ważny ok. 24 godziny; konflikt z cache to częsta przyczyna błędu 401.
• Application Passwords – wbudowane od WordPress 5.6, najlepszy sposób na bezpieczne łączenie aplikacji zewnętrznych. Wygenerujesz je w Użytkownicy → Profil → Hasła aplikacji i używasz w uwierzytelnianiu Basic Auth przez HTTPS.
• Basic Auth – wyłącznie przez bezpieczne połączenie HTTPS, nigdy po HTTP.

Jeśli REST API nadal nie działa, sprawdź warstwę certyfikatu, serwera i własnego kodu.

Błędy SSL/HTTPS i niezgodność adresu

Mixed content (część zasobów ładowana po HTTP), wygasły certyfikat lub niezgodność adresu w Ustawienia → Ogólne (Adres WordPressa vs Adres witryny) potrafią zerwać żądania REST API. Upewnij się, że oba adresy używają tego samego protokołu `https://` i tej samej wersji domeny (z `www` lub bez).

Problemy po stronie serwera i hostingu

Na współdzielonym hostingu typowe blokery to:

• Limit pamięci PHP – ustaw `WP_MEMORY_LIMIT` na co najmniej 256M.
• ModSecurity / WAF – polscy providerzy często mają agresywne reguły, które blokują żądania POST do `wp-json` jako podejrzane. Rozwiązanie to kontakt z hostingiem i prośba o białą listę dla ścieżki REST API.
• Firewall serwerowy – może blokować zapytania o określonej strukturze.

Gdy diagnostyka wskazuje na serwer, najszybszą drogą jest zgłoszenie do supportu hostingu z dokładnym kodem błędu i ścieżką endpointu.

Błędy w kodzie własnego motywu lub wtyczki

Własny kod rejestrujący endpointy potrafi rzucać błąd 500. Włącz tryb debugowania w `wp-config.php`:

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

Logi trafią do `/wp-content/debug.log`. Zawsze obsługuj błędy przez obiekt `WP_Error`, by API zwracało czytelny komunikat zamiast pustej odpowiedzi 500.

Sprawne rozwiązanie problemu zależy od dobrych narzędzi. Oto zestaw, który pokrywa wszystkie scenariusze:

• Query Monitor – darmowa wtyczka pokazująca wszystkie wywołania REST API, czas odpowiedzi, błędy PHP i zapytania do bazy. Najszybciej wskaże, która wtyczka lub funkcja powoduje błąd 500.
• Postman – aplikacja do ręcznego wysyłania żądań do endpointów z dowolnymi nagłówkami i metodą uwierzytelniania. Idealna do testowania Application Passwords i endpointów niepublicznych.
• Stan witryny (Site Health) – wbudowany test dostępności REST API z kodem HTTP.
• Narzędzia deweloperskie przeglądarki (zakładka Network) – pokazują dokładne żądania, jakie edytor blokowy wysyła do `wp-json`, wraz z kodem odpowiedzi. To pierwsze miejsce, gdy edytor zgłasza problem z zapisem.
• Tryb debug WP_DEBUG + debug.log – do wychwytywania błędów PHP w kodzie.

Poniższa tabela pozwala przejść od objawu do rozwiązania w kilka sekund:

Ten schemat pokrywa scenariusze typowe dla polskiego hostingu, gdzie środowiska Nginx i LiteSpeed wraz z ModSecurity są częstsze niż klasyczny Apache.

Najlepszym lekarstwem jest profilaktyka. Aby REST API działało stabilnie:

• Aktualizuj regularnie rdzeń WordPress, motyw i wtyczki – wiele błędów REST API to efekt niezgodności starych wersji.
• Testuj na środowisku staging – żadnej aktualizacji ani nowej wtyczki bezpieczeństwa nie wdrażaj od razu na produkcji.
• Wybieraj dobry hosting pod WordPress – cyberFolks, LH.pl czy Zenbox oferują środowiska zoptymalizowane pod WordPress z rozsądną konfiguracją ModSecurity i wsparciem, które rozumie specyfikę `wp-json`.
• Konfiguruj wtyczki bezpieczeństwa świadomie – z wyjątkami dla REST API zamiast całkowitych blokad.

Kiedy zlecić to specjalistom

Jeśli błąd dotyczy konfiguracji serwera, ModSecurity albo własnego kodu rejestrującego endpointy, a Twoja strona jest narzędziem sprzedaży, każda godzina przestoju kosztuje. W KC Mobile od 20+ lat naprawiamy i utrzymujemy strony WordPress – w ramach opieki nad WordPress (od 299 zł/mies.) monitorujemy działanie, aktualizujemy i reagujemy na takie awarie zanim zauważy je klient.

Projektujemy też nowe, stabilne strony internetowe (od 3000 zł) oraz sklepy WooCommerce (od 8000 zł), w których REST API jest poprawnie skonfigurowane od startu. Masz uszkodzone REST API i potrzebujesz szybkiej pomocy? Skontaktuj się z nami – zdiagnozujemy problem i przywrócimy pełną sprawność witryny.