Kody odpowiedzi HTTP to „język”, w którym serwer rozmawia z przeglądarką – albo z twoją aplikacją (np. SPA, PWA, REST API czy crawlerem). Informują, czy żądanie udało się obsłużyć, czy wystąpił błąd i po czyjej stronie leży problem – klienta czy serwera.
Błędy z zakresu 4xx oznaczają problemy po stronie klienta (zapytania), a błędy 5xx – problemy po stronie serwera. To nie tylko temat dla administratorów – mają realny wpływ na UX, dostępność, SEO i wydajność serwisu.
Świadome używanie statusów 4xx i 5xx podnosi stabilność, dostępność i wiarygodność serwisu – dla użytkowników, robotów wyszukiwarek i narzędzi asystujących.
Poniżej znajdziesz obszerny przewodnik: czym są błędy 4xx i 5xx, co oznaczają najważniejsze kody, jak je diagnozować i jak projektować strony błędów tak, aby były przyjazne, dostępne i „SEO‑bezpieczne”.
1. Czym są kody odpowiedzi HTTP – szybkie przypomnienie
Kod odpowiedzi HTTP to trzycyfrowa liczba, którą serwer odsyła klientowi wraz z odpowiedzią na żądanie.
Każdy kod:
- informuje, jak serwer zareagował na żądanie (powodzenie, przekierowanie, błąd),
- znajduje się w linii statusu odpowiedzi, np.
HTTP/1.1 404 Not Found, - należy do jednej z pięciu głównych klas.
Pięć głównych klas kodów wygląda następująco:
- 1xx – informacje (żądanie przyjęte, w toku);
- 2xx – sukces (żądanie zrealizowane poprawnie);
- 3xx – przekierowania (zasób dostępny gdzie indziej);
- 4xx – błędy po stronie klienta (problem z żądaniem);
- 5xx – błędy po stronie serwera (problem z obsługą żądania).
W praktyce – z punktu widzenia twórcy serwisów WWW – najbardziej problematyczne (i najciekawsze) są 4xx i 5xx, bo sygnalizują sytuacje, w których użytkownik nie dostaje tego, czego oczekuje.
2. Błędy 4xx – kiedy problem jest po stronie klienta
Ogólna idea kodów 4xx
Kody 4xx (Client Error) informują, że serwer rozumie żądanie, ale nie może go obsłużyć ze względu na błąd po stronie klienta lub samego żądania.
Może to być m.in.:
- błędny adres URL (literówka, zły link),
- brak odpowiednich uprawnień / niewłaściwa autoryzacja,
- nieprawidłowe dane wysłane w formularzu lub JSON‑ie,
- przekroczenie limitów (np. zbyt wiele żądań),
- korzystanie z metody HTTP, której dany zasób nie obsługuje.
Błędy 4xx nie muszą oznaczać, że „zepsuł się serwer” – częściej wskazują na problem z nawigacją, uprawnieniami, walidacją lub logiką aplikacji.
Najważniejsze kody 4xx – znaczenie i praktyczne przykłady
400 Bad Request – nieprawidłowe żądanie
Kod 400 oznacza, że serwer nie może obsłużyć żądania, ponieważ jest ono nieprawidłowe – np. ma błędną składnię, brakuje wymaganych parametrów, dane są uszkodzone lub sprzeczne.
Przykłady z praktyki obejmują: użytkownik wysyła formularz z niepoprawnie zserializowanym JSON‑em (np. przez błąd JS); aplikacja mobilna używa starej wersji API z nieobsługiwanymi polami; ręcznie wpisany URL z błędnie kodowanymi znakami.
Dobre praktyki – zwracaj 400 z czytelnym komunikatem (np. w JSON: {"error":"Invalid field 'email'"}); na stronach WWW pokaż użytkownikowi, co dokładnie jest nie tak (błędy przy polach, wskazówki naprawy); zadbaj o dostępność komunikatów błędów formularzy (powiązanie z polami, aria‑describedby, jasny tekst).
401 Unauthorized – brak autoryzacji
Kod 401 informuje, że zasób wymaga uwierzytelnienia, ale dostarczone dane (np. token, cookies) są nieobecne lub nieprawidłowe.
Typowe sytuacje to wywołanie endpointu API bez tokena lub z wygasłym tokenem oraz próba wejścia na stronę tylko dla zalogowanych bez aktywnej sesji.
Dobre praktyki – w aplikacjach WWW kieruj na logowanie z jasnym komunikatem („Aby zobaczyć tę stronę, zaloguj się”); w API zwracaj zwięzłe kody i komunikaty błędów (np. token_expired).
403 Forbidden – brak uprawnień (zabronione)
Kod 403 oznacza, że serwer rozumie żądanie, ale odmawia dostępu do zasobu.
Różnica względem 401: 401 – trzeba się uwierzytelnić; 403 – użytkownik jest uwierzytelniony, ale nie ma uprawnień.
Przykłady: próba wejścia do panelu administratora bez odpowiedniej roli; plik na serwerze z restrykcyjnymi prawami dostępu.
Dobre praktyki –
- nie ujawniaj szczegółów dotyczących wymaganych uprawnień,
- pokaż jasny komunikat: „Nie masz uprawnień do zobaczenia tej strony”,
- zaproponuj alternatywę: powrót na stronę główną lub kontakt z administratorem.
Pod kątem dostępności unikaj jedynie surowego napisu „403 Forbidden”; użyj nagłówka i prostego języka.
404 Not Found – nie znaleziono
404 to najsłynniejszy kod HTTP: serwer działa poprawnie, ale nie znalazł żądanego zasobu pod danym adresem URL.
W praktyce najczęściej: strona została usunięta lub nigdy nie istniała; link jest błędny (literówka, stary adres); użytkownik kliknął nieaktualny odnośnik.
Dlaczego 404 jest tak ważny? Dla UX – źle zaprojektowana strona 404 frustruje i zwiększa współczynnik odrzuceń; dla SEO – masowe 404 mogą świadczyć o złej strukturze serwisu lub migracji bez przekierowań.
Dobre praktyki projektowania strony 404 obejmują:
- zachowanie prawidłowego kodu 404 w odpowiedzi HTTP (nie 200),
- czytelny, ludzki komunikat wyjaśniający, co się stało i co można zrobić dalej,
- spójny layout z resztą serwisu (menu, stopka, styl).
W komunikacie wyjaśnij wprost:
- co się stało („Taka strona nie istnieje”),
- co użytkownik może teraz zrobić,
- gdzie szukać dalej odpowiednich treści.
Zadbaj też o elementy nawigacyjne i wsparcie:
- widoczne odnośniki do strony głównej i głównych sekcji,
- pole wyszukiwania,
- link do mapy serwisu.
Pod kątem dostępności pamiętaj o:
- poprawnej hierarchii nagłówków (h1: „Strona nie została znaleziona”),
- języku zgodnym z deklaracją
lang, - unikaniu wyłącznie graficznych komunikatów błędów.
405 Method Not Allowed – niedozwolona metoda
Kod 405 informuje, że żądanie dotyczy istniejącego zasobu, ale użyta metoda HTTP nie jest dozwolona (np. POST na zasób, który obsługuje tylko GET). Przykładowo: formularz wysyła POST na adres przyjmujący tylko GET albo aplikacja JS próbuje wykonać PUT na endpoint obsługujący tylko POST.
Dobrą praktyką jest odesłanie w nagłówku Allow listy dozwolonych metod.
406 Not Acceptable – nieakceptowalna odpowiedź
Kod 406 oznacza, że serwer mógłby odpowiedzieć, ale nie jest w stanie wygenerować odpowiedzi w formacie, który klient akceptuje (nagłówek Accept). W aplikacjach webowych rzadki; częściej w API, gdy klient wymaga np. application/json, a serwer ma tylko text/html.
408 Request Timeout – przekroczony czas żądania
408 sygnalizuje, że klient zbyt długo zwlekał z wysłaniem pełnego żądania i serwer przerwał oczekiwanie. Może wystąpić przy bardzo wolnym połączeniu lub błędach sieciowych.
409 Conflict – konflikt stanu
Kod 409 pojawia się, gdy żądanie jest poprawne składniowo, ale jego wykonanie spowodowałoby konflikt z aktualnym stanem zasobu. Przykłady: edycja dokumentu już zmodyfikowanego przez innego użytkownika; próba dodania rekordu z istniejącym kluczem.
410 Gone – zasób zniknął na stałe
410 oznacza, że zasób kiedyś istniał, ale został trwale usunięty i nie wróci. W odróżnieniu od 404, 410 komunikuje: to nie wróci – usuń linki.
412 Precondition Failed – warunek wstępny niespełniony
Kod 412 informuje, że warunki wstępne w nagłówkach żądania (np. If-Match, If-Unmodified-Since) nie zostały spełnione, więc serwer odmawia wykonania. Najczęściej w API i przy optymistycznym blokowaniu współbieżności.
415 Unsupported Media Type – nieobsługiwany typ danych
415 sygnalizuje, że serwer nie obsługuje typu danych wskazanego w Content-Type (np. wysyłasz application/xml, a endpoint przyjmuje tylko application/json).
429 Too Many Requests – zbyt wiele żądań
Kod 429 oznacza, że klient wysłał zbyt wiele żądań w danej jednostce czasu – mechanizm ograniczania ruchu (rate limiting). Przykłady: intensywne odpytywanie API przez bota; błędna pętla w kodzie generująca wiele żądań.
Dobre praktyki: informuj o limicie i czasie odblokowania (nagłówek Retry-After); w UI pokazuj komunikat zachęcający do odczekania przy masowych akcjach.
3. Błędy 5xx – gdy zawodzi serwer
Ogólna idea kodów 5xx
Kody 5xx (Server Error) informują, że żądanie było poprawne, ale serwer nie mógł go obsłużyć z powodu błędu po swojej stronie.
Przyczyny to m.in.:
- błędy w kodzie aplikacji,
- problemy z bazą danych,
- przeciążenie serwera,
- błędna konfiguracja proxy lub bramy,
- awarie infrastruktury.
Dla użytkownika różnica między 4xx a 5xx jest niewidoczna – widzi po prostu, że „strona nie działa”. Dla zespołu technicznego to kluczowe informacje diagnostyczne.
Najpopularniejsze kody 5xx
500 Internal Server Error – wewnętrzny błąd serwera
Kod 500 mówi, że na serwerze wystąpił nieoczekiwany błąd, który uniemożliwił wykonanie żądania. To kod „awaryjny” – używany, gdy nie ma bardziej precyzyjnego statusu.
Przykłady:
- nieobsłużony wyjątek w kodzie aplikacji,
- błąd w szablonie (np. odwołanie do nieistniejącej zmiennej),
- fatal error w PHP lub błędy runtime w frameworku.
Dobre praktyki –
- na produkcji nie wyświetlaj stack trace użytkownikowi,
- loguj szczegóły błędu po stronie serwera,
- pokaż użytkownikowi przyjazną, dostępną stronę błędu 500 (z opcją powrotu i jasnym komunikatem).
501 Not Implemented – nie zaimplementowano
501 oznacza, że serwer nie obsługuje funkcjonalności wymaganej do obsługi żądania. Rzadko spotykany w typowych aplikacjach WWW.
502 Bad Gateway – błędna brama
Kod 502 wskazuje na problem z komunikacją między serwerami (proxy/balancer ↔ serwer docelowy). Serwer pośredniczący otrzymał nieprawidłową odpowiedź od kolejnego serwera w łańcuchu.
Przykładowe przyczyny:
- serwer aplikacyjny zwraca niekompletną lub uszkodzoną odpowiedź,
- błąd konfiguracji proxy,
- zbyt długie przetwarzanie żądania (w części konfiguracji może skutkować 502).
503 Service Unavailable – usługa niedostępna
503 sygnalizuje, że serwer tymczasowo nie może obsłużyć żądania, np. z powodu przeciążenia lub zaplanowanych prac serwisowych.
Typowe scenariusze:
- aktualizacja serwisu,
- awaria jednego z kluczowych komponentów (np. bazy),
- chwilowe przeciążenie ruchem.
Dobrą praktyką jest ustawienie nagłówka Retry-After, informującego, kiedy warto spróbować ponownie.
Kluczowe dla SEO – przy planowanych przerwach technicznych używaj 503, a nie 500 czy 404.
504 Gateway Timeout – przekroczony czas odpowiedzi bramy
504 oznacza, że serwer pośredniczący (gateway/proxy) nie doczekał się odpowiedzi od serwera docelowego w wyznaczonym czasie.
Może wynikać np. z:
- wolnych zapytań do bazy,
- deadlocków,
- problemów z siecią między serwerami.
Inne kody 5xx
Spotyka się także m.in. 507 Insufficient Storage (niski poziom dostępnej pamięci / miejsca na dysku) oraz 508 Loop Detected (wykryta pętla w przetwarzaniu żądania, np. w WebDAV). W klasycznym serwisie WWW najczęściej zobaczysz jednak 500, 502, 503 i 504.
4. 4xx i 5xx a SEO, analityka i jakość serwisu
Jak kody błędów wpływają na SEO
Z punktu widzenia wyszukiwarek błędy 4xx i 5xx to sygnały o problemach z dostępnością treści. Statusy 4xx (szczególnie 404, 410) mówią, że dana treść jest niedostępna, a 5xx sygnalizują problemy z serwerem – jeśli trwają, mogą obniżyć ocenę jakości serwisu i doprowadzić do wyindeksowania części treści.
Z punktu widzenia SEO warto:
- kontrolować liczbę błędów 404 (np. w narzędziach analitycznych i crawlerach),
- przekierowywać (301/302) ważne stare adresy na nowe, zamiast zostawiać tysiące 404,
- używać 410, gdy świadomie usuwasz treść bez odpowiednika,
- przy pracach serwisowych ustawiać 503, nie 404 i nie 200 ze stroną serwisową.
Analiza błędów na podstawie logów i narzędzi
Błędy 4xx i 5xx warto monitorować w kilku źródłach:
- w logach serwera (access log, error log),
- w panelach hostingowych i CDN,
- w systemach APM (Application Performance Monitoring),
- w raportach narzędzi SEO (błędy indeksowania, niedostępne strony).
Dzięki temu można:
- wyłapać złamane linki (broken links) – np. przeoczone po migracji,
- zidentyfikować błędne implementacje formularzy i API,
- zauważyć przeciążenie serwera lub wadliwą konfigurację proxy (502, 504).
5. Strony błędów a dostępność – jak zaprojektować dobre 4xx/5xx
Z perspektywy dostępności i UX błędy 4xx/5xx są krytycznymi momentami w ścieżce użytkownika. To, co pokażesz zamiast treści, bezpośrednio wpływa na:
- zrozumiałość sytuacji,
- poziom frustracji,
- zdolność użytkownika do kontynuowania zadania.
Zasady ogólne (WCAG, UX, copywriting)
Dobra strona błędu (np. 404, 403, 500, 503) powinna:
- jasno wyjaśniać, co się stało,
- używać prostego języka, bez żargonu,
- wskazywać użytkownikowi, co może zrobić dalej,
- zachowywać spójny layout z resztą serwisu (menu, stopka, styl),
- spełniać zasady dostępności (WCAG) – odpowiedni kontrast, obsługa klawiaturą, poprawne znaczniki semantyczne.
Dalsze kroki, które warto zaproponować użytkownikowi:
- wrócić do strony głównej,
- użyć wyszukiwarki,
- przejść do popularnych sekcji,
- skontaktować się z pomocą (w krytycznych procesach).
Semantyka i techniczne detale dostępności
Kilka konkretnych zaleceń dla czytelności i A11y:
- użyj nagłówka h1 z jasnym komunikatem („Strona nie została znaleziona” / „Błąd serwera”),
- zachowaj hierarchię nagłówków (h2 – wyjaśnienie, h3 – sugestie kroków),
- zapewnij, by komunikat o błędzie był tekstem, nie tylko grafiką,
- umieść link „przejdź do treści” (skip link),
- nie blokuj nawigacji – globalne menu i stopka powinny być dostępne,
- przy błędach formularza powiąż komunikaty z polami (
aria-describedby,aria-invalid).
Prawidłowy kod HTTP + własny szablon
Częsty błąd: projektujemy świetną stronę 404, ale serwer zwraca kod 200. Skutki to m.in. soft 404 w SEO oraz zaburzona analityka.
Dobierz właściwy status do sytuacji:
- przy nieistniejącej stronie – zwracaj 404 (lub 410 przy trwałym usunięciu),
- przy błędzie serwera – 500 (lub bardziej szczegółowy kod 5xx),
- przy pracach serwisowych – 503.
A dopiero w treści HTML prezentuj swój dostosowany szablon błędu.
6. Błędy 4xx/5xx w API i aplikacjach SPA
W nowoczesnych aplikacjach (REST/GraphQL API, SPA, PWA) kody 4xx sygnalizują problemy z żądaniem, a 5xx – błędy po stronie serwera, często wraz z kodem i szczegółami błędu.
Zawsze zwracaj spójny format odpowiedzi błędów – np. JSON z polami code, message, details.
Rozróżniaj typy błędów według znaczenia kodów:
- 400 – walidacja lub składnia,
- 401/403 – uwierzytelnienie i autoryzacja,
- 404 – brak zasobu,
- 409 – konflikt,
- 429 – limit żądań,
- 500+ – problemy serwera.
Zalecane reakcje po stronie SPA:
- 401 – wyloguj użytkownika lub pokaż okno logowania,
- 403 – komunikat „brak uprawnień”,
- 404 – komponent „nie znaleziono”,
- 5xx – ekran „problem po naszej stronie, spróbuj ponownie”.
Wiele API dokumentuje, że odpowiedzi 4xx/5xx zawierają dodatkowy opis – warto przyjąć ten sam wzorzec we własnych interfejsach.
7. Podsumowanie praktyczne dla twórców serwisów WWW
- Różnica 4xx vs 5xx – 4xx to problem z żądaniem po stronie klienta, 5xx to problem z obsługą żądania po stronie serwera;
- Precyzyjne kody – używaj możliwie szczegółowych statusów, nie wszystko 404 lub 500;
- Dostępne strony błędów – zrozumiały komunikat, nawigacja, wyszukiwarka, poprawna semantyka;
- SEO i migracje – poprawne statusy HTTP, sensowne przekierowania, świadome użycie 410 i 503;
- Monitoring – śledź logi, APM i raporty SEO, bo 4xx/5xx wskazują realne problemy do naprawy.
Świadome korzystanie z kodów 4xx i 5xx to prosty sposób na lepszy UX, lepsze SEO i mniej awarii.
