Błąd 500, 502, 503 i 504 — co znaczą i kogo wołać, gdy pojawią się na Waszej stronie

Jeśli widzisz ten błąd na cudzej stronie — sklepie, banku, urzędzie — to nie jest problem Twojego komputera ani połączenia. Kod zaczynający się od 5 znaczy, że zawiódł serwer po drugiej stronie. Odśwież stronę za kilka minut; jeśli nie pomoże, spróbuj później. Nic więcej nie da się zrobić z tej strony ekranu.

Jeśli to Wasza strona, kod błędu jest cenniejszy, niż się wydaje. Nie mówi tylko, że „coś nie działa". Mówi, na którym odcinku drogi od przeglądarki do bazy danych coś zawiodło — a to rozstrzyga, kogo trzeba zawołać: firmę hostingową, wykonawcę strony czy dostawcę usługi, która stoi pomiędzy.

Ten tekst jest o tym, jak ten kod przeczytać. O tym, jak w ogóle dowiedzieć się o błędzie, zanim zadzwoni klient, piszemy przy monitoringu strony.

Cztery kody, cztery miejsca w łańcuchu

Kiedy ktoś otwiera stronę, jego przeglądarka rzadko rozmawia bezpośrednio z programem, który tę stronę tworzy. Po drodze stoi zwykle pośrednik — sieć dostarczania treści (CDN), serwer WWW przyjmujący ruch albo inny serwer pośredniczący — a za nim aplikacja: WordPress, sklep, system zarządzania treścią. Aplikacja z kolei sięga do bazy danych i do usług zewnętrznych. Każdy z tych elementów może zawieść i każdy zawodzi inaczej.

Wszystkie cztery kody są zdefiniowane w specyfikacji HTTP i każda definicja wskazuje miejsce awarii:

• 500 — serwer napotkał „an unexpected condition", które uniemożliwiło obsłużenie żądania. Awaria w aplikacji.
• 502 — serwer, działając jako pośrednik, „received an invalid response" od serwera, do którego się zwrócił. Awaria między pośrednikiem a aplikacją: aplikacja odpowiedziała, ale źle — albo nie odpowiedziała wcale, bo nie działa.
• 503 — serwer jest „currently unable to handle the request due to a temporary overload or scheduled maintenance". Chwilowa odmowa: przeciążenie albo prace.
• 504 — pośrednik „did not receive a timely response" od serwera za nim. Aplikacja nie zdążyła.

Z tego wynika pierwsza zasada czytania błędów: ta sama awaria widziana z przeglądarki zawsze wygląda tak samo — strona się nie otwiera — ale kod mówi, gdzie szukać. Wykonawca, który przy każdym błędzie zaczyna od restartu serwera, ignoruje połowę informacji, którą serwer mu podał.

Błąd 500 — wewnętrzny błąd serwera

Błąd 500 to najczęściej wyszukiwany z kodów serwera i najczęściej źle rozumiany. Brzmi jak „serwer się zepsuł". Znaczy coś węższego: program, który miał obsłużyć to konkretne żądanie, natrafił na sytuację, której nie przewidział, i przerwał pracę. Serwer działa — odpowiedział przecież, podając kod. Zawiodła aplikacja, i często tylko przy jednym rodzaju żądania.

Mamy na to świeży przykład z własnego serwisu. Przez kilka godzin wgrywanie plików do naszego systemu zarządzania treścią kończyło się błędem 500 i w notatkach roboczych trafiło do rubryki „awaria produkcji — czekamy". Strona w tym czasie działała normalnie, a inne zapisy przechodziły bez problemu. Przyczyną okazała się forma samego żądania: jedno pole wysyłane w formacie, którego aplikacja nie obsługiwała przy wgrywaniu plików. Po zmianie formy ten sam serwer przyjął ten sam plik za pierwszym razem. Lekcja jest ogólna: 500 mówi, że coś wysypało się w kodzie obsługującym to żądanie. Zanim ktokolwiek zacznie szukać awarii serwera, warto sprawdzić, czy błąd pojawia się wszędzie, czy tylko przy jednej czynności.

Przy stronach na WordPressie przyczyna błędu 500 jest zwykle jedna z trzech:

• Wtyczka albo motyw — najczęściej zaraz po aktualizacji, gdy nowa wersja nie współpracuje z resztą. Dlatego aktualizuje się po jednej pozycji, z kopią przed: wtedy wiadomo, co odkręcić.
• Wersja PHP — zmiana na serwerze, po której starszy kod przestaje działać. Zdarza się także bez Waszego udziału, kiedy dostawca hostingu wyłącza starą wersję.
• Limit zasobów — skrypt przekroczył pamięć albo czas, na który pozwala serwer. Typowe przy dużych importach, generowaniu miniatur i kopiach zapasowych robionych przez wtyczkę.

Dziennik błędów serwera — dostępny w panelu hostingu albo u wykonawcy — zwykle podaje przyczynę wprost, z nazwą pliku i wiersza. Pierwsze pytanie do wykonawcy przy błędzie 500 brzmi więc: co jest w dzienniku błędów z tej minuty? Odpowiedź „zrestartowaliśmy serwer i działa" znaczy, że nikt tam nie zajrzał, a błąd wróci przy następnym takim samym żądaniu.

Błąd 500 — jak naprawić, krok po kroku

Kolejność, która najczęściej prowadzi do przyczyny najkrótszą drogą — także wtedy, gdy robi to wykonawca, a Wy chcecie wiedzieć, czy robi to dobrze:

1. Czy błąd pojawia się wszędzie, czy przy jednej czynności. Strona główna, podstrona, panel, formularz, koszyk. Błąd tylko przy jednej czynności zawęża poszukiwania do jednej funkcji — i prawie wyklucza „awarię serwera".
2. Dziennik błędów z tej minuty. W panelu hostingu albo u wykonawcy. W WordPressie można dodatkowo włączyć zapis błędów do pliku w katalogu wp-content — ustawieniem, które zapisuje błędy do dziennika, zamiast pokazywać je odwiedzającym.
3. Ostatnia zmiana. Aktualizacja, nowa wtyczka, zmiana wersji PHP, wdrożenie. Jeśli błąd zaczął się tuż po niej, odkręcenie tej jednej zmiany jest szybsze niż szukanie przyczyny.
4. Wyłączenie winnej wtyczki bez panelu. Jeśli do panelu nie da się wejść, wtyczkę wyłącza się, zmieniając nazwę jej katalogu na serwerze — WordPress przestaje ją wtedy wczytywać. Tę samą metodę opisujemy przy aktualizacjach.
5. Kopia zapasowa, jeśli przyczyny nie widać. Przywrócenie stanu sprzed awarii to decyzja o tym, ile danych od tamtej chwili się straci — dlatego podejmuje ją właściciel, a warunkiem jest kopia, którą ktoś kiedyś odtworzył.

Przy 502 i 503 kolejność jest podobna, tylko punkt drugi dotyczy dziennika pośrednika i obciążenia serwera, a punkt trzeci — wdrożeń i zmian w planie hostingowym.

„Wystąpił krytyczny błąd na tej witrynie"

Właściciele stron na WordPressie częściej niż kod 500 widzą ten komunikat. To WordPress, który od wersji 5.2 przechwytuje najpoważniejsze błędy aplikacji: zamiast pustej białej strony pokazuje odwiedzającym komunikat, że strona ma problemy techniczne.

Ważniejsze jest to, co dzieje się w tle. Według notatki zespołu WordPressa system wysyła wtedy wiadomość na adres e-mail administratora strony z tajnym linkiem do trybu odzyskiwania. Po wejściu w ten link wtyczki albo motywy, które powodują błąd, zostają wstrzymane — ale tylko dla osoby, która z linku skorzystała. Może ona zalogować się do panelu, wyłączyć winną wtyczkę albo przywrócić poprzednią wersję, podczas gdy odwiedzający nadal widzą komunikat o błędzie.

Mechanizm jest dobry, pod jednym warunkiem: ktoś musi tę wiadomość dostać. Adres administratora ustawia się przy instalacji i rzadko ktokolwiek do niego wraca. Jeśli stronę kilka lat temu zakładała agencja albo pracownik, który już nie pracuje w firmie, link odzyskiwania trafia do skrzynki, której nikt nie czyta. To ten sam problem, który opisujemy przy obsłudze strony w kontekście domeny i dostępów: adresy kontaktowe w systemach, od których zależy strona, powinny prowadzić do kogoś w firmie. Sprawdzenie zajmuje minutę — w panelu WordPressa, w ustawieniach ogólnych.

Błąd 502 Bad Gateway — co to znaczy

„Bad Gateway" po polsku to mniej więcej „zła brama". Brama to pośrednik: serwer, który przyjmuje żądanie od przeglądarki i przekazuje je dalej, do aplikacji. Błąd 502 znaczy, że pośrednik zapytał aplikację, a to, co dostał z powrotem, nie nadawało się do odesłania — albo nie dostał nic, bo aplikacja nie przyjęła połączenia.

W praktyce 502 najczęściej oznacza, że program obsługujący stronę za pośrednikiem nie działa albo właśnie się restartuje. Serwer WWW stoi, sieć działa, ale proces, który miał wygenerować stronę, padł — z braku pamięci, po błędzie, w trakcie wdrożenia nowej wersji. Dlatego 502 bywa krótki: pojawia się na kilkadziesiąt sekund w trakcie aktualizacji i znika.

Co z tego wynika dla właściciela:

• 502 trwający sekundy w czasie wdrożenia to zwykle sposób, w jaki wdrożenie jest zrobione, a nie awaria. Da się go uniknąć, ale to decyzja o sposobie wdrażania, nie naprawa.
• 502 powtarzający się bez wdrożeń to aplikacja, która pada. Pytanie do wykonawcy: dlaczego proces się zatrzymuje i co jest w jego dzienniku.
• 502 od dostawcy CDN — jeśli strona stoi za siecią dostarczania treści — znaczy, że CDN działa, ale nie może się porozumieć z Waszym serwerem. Najpierw sprawdza się serwer, nie CDN.

Błąd 503 — serwer chwilowo niedostępny

503 to jedyny z tych kodów, który strona powinna czasem zwracać celowo. Specyfikacja przewiduje go dla dwóch sytuacji: przeciążenia i zaplanowanych prac. W obu przypadkach serwer może dodać nagłówek Retry-After, który mówi, kiedy warto spróbować ponownie.

Przeciążenie oznacza, że serwer przyjmuje więcej żądań, niż jest w stanie obsłużyć, i odmawia części z nich, zamiast obsłużyć wszystkie za wolno. Przy hostingu współdzielonym 503 bywa też sposobem, w jaki dostawca informuje, że strona przekroczyła przydzielone zasoby. Jeśli pojawia się regularnie w godzinach największego ruchu, to sygnał, że plan hostingowy jest za mały albo strona zużywa za dużo na jedno wyświetlenie — co zwykle widać też w Core Web Vitals.

Prace zaplanowane to druga sytuacja i tu zasada jest prosta: jeśli strona ma być na chwilę niedostępna, niech odpowiada 503, a nie stroną „trwa przerwa techniczna" z kodem 200. Dla odwiedzającego oba wyglądają tak samo. Dla wyszukiwarki pierwsze znaczy „wróć później", drugie — „tak teraz wygląda ta strona". WordPress przy aktualizacjach robi to sam: na czas instalacji wyświetla krótki komunikat o przerwie serwisowej właśnie z kodem 503 i nagłówkiem Retry-After ustawionym na 600 sekund — tak jest to zapisane w jego kodzie źródłowym.

Błąd 504 Gateway Timeout

504 jest bliskim krewnym 502, z jedną różnicą: pośrednik nie dostał złej odpowiedzi — nie dostał żadnej na czas. Aplikacja pracowała, ale tak długo, że pośrednik przestał czekać.

Typowe przyczyny to operacje, które z natury trwają długo, uruchomione w trakcie zwykłego wyświetlenia strony: import produktów, generowanie raportu, kopia zapasowa robiona przez wtyczkę, wolne zapytanie do bazy przy dużej liczbie wpisów, zewnętrzna usługa — płatności, kurier, system magazynowy — która sama odpowiada powoli. Każda z nich może działać poprawnie i jednocześnie powodować 504, bo pośrednik ma własny limit czasu, niezależny od aplikacji.

Dlatego 504 rzadko naprawia się „na serwerze". Naprawia się go w aplikacji: długie operacje przenosi się do zadań wykonywanych w tle, zamiast wykonywać je w czasie wyświetlania strony, a wolne zapytania — optymalizuje. Podniesienie limitu czasu u pośrednika bywa szybkim obejściem, ale znaczy tylko, że odwiedzający będą dłużej patrzeć na ładującą się stronę, zanim zobaczą ten sam problem.

Kody 52x za Cloudflare

Jeśli strona stoi za Cloudflare — a stoi za nim wiele stron, w tym nasza — zamiast 502 i 504 zobaczycie często kody z serii 52x. To nie są kody ze specyfikacji HTTP, tylko własne oznaczenia Cloudflare, które precyzują, co poszło nie tak między nim a Waszym serwerem. Według dokumentacji Cloudflare:

• 520 — serwer zwrócił nieznany błąd,
• 521 — serwer nie działa (odmówił połączenia),
• 522 — upłynął czas na nawiązanie połączenia,
• 524 — upłynął czas oczekiwania na odpowiedź.

Wszystkie cztery mówią to samo co 502 i 504: Cloudflare działa, problem jest za nim, na Waszym serwerze albo w drodze do niego. Kontakt z pomocą Cloudflare rzadko coś zmieni; kontakt z hostingiem — zwykle tak.

Co z błędami serwera robi Google

Krótka awaria nie zaszkodzi pozycjom w wyszukiwarce. Długa — tak, i Google opisuje ten mechanizm w swojej dokumentacji dość dokładnie.

Błędy 5xx — a także 429 — sprawiają, że roboty Google chwilowo zwalniają pobieranie stron z Waszego serwera, proporcjonalnie do liczby adresów, które zwracają błąd. Zaindeksowane adresy zostają w indeksie, ale te, które zwracają błąd serwera trwale, są z niego ostatecznie usuwane. Kiedy serwer znowu odpowiada poprawnie, Google stopniowo wraca do zwykłego tempa.

W praktyce oznacza to, że najgroźniejszy nie jest pojedynczy błąd, tylko błąd, o którym nikt nie wie: strona sklepu, która od tygodnia zwraca 500 przy jednym typie produktów, podstrona z formularzem, która przestała działać po aktualizacji. Takie adresy znikają z wyników po cichu. W Search Console widać je w raporcie o indeksowaniu stron jako błędy serwera — i to jest jeden z niewielu raportów, który warto przeglądać co tydzień, nie co kwartał.

429 Too Many Requests — kiedy strona broni się sama

429 nie jest kodem z serii 5xx, ale należy do tej samej rozmowy. Specyfikacja definiuje go jako odpowiedź na zbyt wiele żądań w krótkim czasie — mechanizm ochrony przed botami, atakami i nadmiernym ruchem. Tak jak przy 503, serwer może podać Retry-After.

Właściciel strony powinien o nim wiedzieć z jednego powodu: zapora, która broni strony przed botami, potrafi zablokować także roboty wyszukiwarek. Google traktuje 429 jak błąd serwera i zwalnia pobieranie; jeśli trwa to długo, skutki są takie jak przy każdym trwałym błędzie. Po włączeniu nowej ochrony przed botami — w hostingu, w CDN albo wtyczką — warto sprawdzić w Search Console, czy robot Google nie zaczął dostawać odmów.

Kogo wołać — kod, miejsce, adresat

Kod błędu nie zastąpi diagnozy, ale pozwala zacząć od właściwej osoby.

Jeśli stroną opiekuje się firma zewnętrzna, ta tabela jest też testem umowy: czy wiadomo, kto jest adresatem w każdym wierszu, i w jakim czasie ma zareagować. Jak to zapisać, rozkładamy przy obsłudze strony.

Czego w tym tekście świadomie nie ma

• Błędów 404, 403, 401 i 400 — to błędy po stronie żądania, z inną diagnozą i innym adresatem; opisujemy je razem z mapą wszystkich kodów w tekście o błędzie 404.
• Przekierowań 301 i 302 — migracja strony, gdzie są sercem całej operacji.
• Tego, jak wykryć błąd, zanim zobaczy go klient — monitoring strony.
• Przywracania strony, gdy przyczyny nie widać — kopia zapasowa.

Najkrótsze podsumowanie: kod błędu serwera to adres, nie diagnoza. 500 każe zajrzeć do aplikacji i jej dziennika, 502 i 504 — na połączenie między pośrednikiem a aplikacją, 503 — na obciążenie albo prace, 52x — na serwer za Cloudflare. A zanim ktokolwiek uzna, że „serwer leży", warto sprawdzić, czy błąd pojawia się wszędzie, czy tylko przy jednej czynności — nasz własny 500 był właśnie tym drugim.