Kody statusu HTTP to znormalizowany język, za pomocą którego serwery WWW komunikują wynik żądań klientów do przeglądarek i aplikacji. Te trzycyfrowe odpowiedzi od razu wskazują, czy żądanie zakończyło się sukcesem, wystąpił błąd po stronie klienta, czy też doszło do awarii po stronie serwera.
Precyzyjne kody statusu pomagają programistom i administratorom szybko diagnozować problemy, a użytkownikom rozumieć, co stało się podczas dostępu do zasobu. Zrozumienie tych kodów wykracza daleko poza słynny błąd 404 „Not Found” i obejmuje opanowanie całej taksonomii odpowiedzi — od informacyjnych komunikatów o trwającym przetwarzaniu, przez trwałe przekierowania, po konkretne błędy serwera.
Podstawy kodów statusu HTTP i ich mechanizm komunikacji
Kody statusu HTTP są fundamentalnym składnikiem protokołu Hypertext Transfer Protocol i krytycznym mechanizmem komunikacji między serwerami a klientami. Za każdym razem, gdy przeglądarka wysyła żądanie — kliknięcie linku, wysłanie formularza, pobranie obrazu — serwer odpowiada nie tylko treścią, ale także trzycyfrowym kodem statusu w nagłówkach odpowiedzi.
Kody podzielone są na pięć klas; o kategorii decyduje pierwsza cyfra. Dzięki temu klient (przeglądarka lub aplikacja) może automatycznie dobrać właściwą reakcję: wyświetlić treść, podążyć za przekierowaniem lub obsłużyć błąd.
Dla szybkiej orientacji w klasach kodów statusu HTTP, zapamiętaj krótką ściągawkę:
- 1xx – odpowiedzi informacyjne, żądanie jest w toku;
- 2xx – powodzenie, żądanie zrealizowane poprawnie;
- 3xx – dodatkowe działania (przekierowania) wymagane;
- 4xx – błąd po stronie klienta, należy poprawić żądanie;
- 5xx – błąd po stronie serwera, problem z przetwarzaniem żądania.
Struktura komunikacji jest zdefiniowana przez RFC 9110. Serwer wysyła linię statusu z wersją HTTP, kodem i frazą (reason phrase), np.:
HTTP/1.1 200 OK
HTTP/1.1 404 Not Found
Klient analizuje kod i decyduje o dalszych krokach: przy sukcesie wyświetla treść, przy przekierowaniu podąża za adresem z nagłówka Location, a przy błędzie wyświetla komunikat lub podejmuje działania naprawcze.
W API (zwłaszcza REST) kody statusu przekazują nie tylko „czy się udało”, ale też „co dalej ma zrobić klient”. Przykładowo 429 „Too Many Requests” sugeruje backoff, 503 „Service Unavailable” wskazuje na problem tymczasowy, a 400 „Bad Request” oznacza trwały błąd w żądaniu.
Odpowiedzi informacyjne – seria 1xx
Seria 1xx oznacza stan przejściowy przed wysłaniem finalnej odpowiedzi; to odpowiedzi bez ciała, zawierające jedynie nagłówki.
100 „Continue” ma zastosowanie przy dużych ciałach żądań: po Expect: 100-continue serwer potwierdza, że można kontynuować przesył danych. 101 „Switching Protocols” informuje o przełączeniu na inny protokół (np. WebSocket lub HTTP/2) po żądaniu z nagłówkiem Upgrade. 102 „Processing” (np. w WebDAV) komunikuje, że żądanie jest przetwarzane, a 103 „Early Hints” pozwala wysłać z wyprzedzeniem nagłówki (np. Link) w celu przyspieszenia ładowania.
Odpowiedzi sukcesu – seria 2xx
Kody 2xx oznaczają, że żądanie zostało odebrane, zrozumiane i pomyślnie zrealizowane.
200 „OK” obejmuje udane GET, a także PUT/PATCH i POST, gdy nie tworzysz nowego zasobu. 201 „Created” informuje, że utworzono nowy zasób (zwykle po POST/PUT) i powinien zawierać nagłówek Location z URI nowego obiektu. Rozróżnienie 200 vs 201 jest kluczowe semantycznie dla klientów API.
202 „Accepted” oznacza, że żądanie przyjęto do przetwarzania (scenariusze asynchroniczne). 204 „No Content” mówi o sukcesie bez ciała odpowiedzi (np. po DELETE). 206 „Partial Content” obsługuje zapytania zakresowe (Range) i zwraca fragment zasobu z nagłówkami Content-Range.
Kody przekierowań – seria 3xx
Kody 3xx mówią, że do ukończenia żądania potrzebna jest dodatkowa akcja, zwykle przekierowanie pod inny URL. 304 „Not Modified” sygnalizuje, że kopia w cache klienta jest aktualna, więc można ją wykorzystać.
301 „Moved Permanently” oznacza trwałe przeniesienie zasobu i jest silnym sygnałem SEO. 302 „Found” to przekierowanie tymczasowe (historycznie z możliwą zmianą metody na GET). 307 „Temporary Redirect” i 308 „Permanent Redirect” precyzują zachowanie metody i ciała: nie powinny się zmieniać podczas podążania za przekierowaniem. 303 „See Other” nakazuje pobrać reprezentację pod innym URI metodą GET, często po udanym POST.
Poniżej praktyczna ściągawka ułatwiająca dobór kodu przekierowania:
| Kod | Trwałość | Zachowanie metody | Typowy scenariusz |
|---|---|---|---|
| 301 | trwałe | metoda może ulec zmianie | docelowa zmiana URL, konsolidacja domen |
| 302 | tymczasowe | często zmiana na GET | krótkotrwałe przeniesienie zasobu |
| 303 | tymczasowe | zawsze użyj GET | redirect po POST do strony potwierdzenia |
| 307 | tymczasowe | metoda i ciało nie zmieniają się | przekierowania z zachowaniem metody (np. POST) |
| 308 | trwałe | metoda i ciało nie zmieniają się | docelowa zmiana URL bez zmiany metody |
Błędy po stronie klienta – seria 4xx, część pierwsza
Kody 4xx informują, że serwer wykrył problem w żądaniu klienta. Odpowiedzialność za naprawę leży po stronie klienta: poprawa składni, dostarczenie uwierzytelnienia, uprawnień lub parametrów.
400 „Bad Request” — błąd składni lub danych wejściowych (np. niepoprawny JSON, brak nagłówków). 401 „Unauthorized” — brak lub niepowodzenie uwierzytelnienia; odpowiedź zawiera WWW-Authenticate. 403 „Forbidden” — klient jest znany, ale nie ma uprawnień do zasobu.
Różnica 401 vs 403 jest krytyczna: 401 = „nie wiem, kim jesteś”, 403 = „wiem, kim jesteś, ale nie możesz tego zrobić”.
Błędy po stronie klienta – seria 4xx, część druga
404 „Not Found” — zasób nie istnieje pod wskazanym adresem. Dobra obsługa 404 to spersonalizowane strony błędu z podpowiedziami i linkami. 410 „Gone” mówi o trwałym, zamierzonym usunięciu zasobu i przyspiesza deindeksację.
405 „Method Not Allowed” — zasób istnieje, ale nie obsługuje danej metody; dodaj Allow z dozwolonymi metodami. 408 „Request Timeout” — serwer zbyt długo czekał na żądanie. 413 „Payload Too Large” i 414 „URI Too Long” — rozmiary przekraczają limity.
415 „Unsupported Media Type” — nieobsługiwany typ mediów w żądaniu (np. JSON z Content-Type: text/plain). 422 „Unprocessable Content” — składnia poprawna, ale dane naruszają reguły biznesowe. 429 „Too Many Requests” — przekroczono limity (rate limiting), zwykle z Retry-After.
Najważniejsze kody 4xx w pigułce:
| Kod | Znaczenie | Co zrobić po stronie klienta |
|---|---|---|
| 400 | błąd składni/danych | zweryfikować payload i nagłówki |
| 401 | brak uwierzytelnienia | dostarczyć poprawne poświadczenia |
| 403 | brak uprawnień | poprawić autoryzację/role |
| 404 | zasób nie istnieje | sprawdzić URL/identyfikatory |
| 422 | błąd walidacji semantycznej | naprawić dane zgodnie z regułami |
| 429 | przekroczone limity | wprowadzić backoff, respektować Retry-After |
418 „I’m a Teapot” to humorystyczny wyjątek z RFC 2324 — nie używaj w produkcyjnych API.
Błędy po stronie serwera – seria 5xx
Kody 5xx oznaczają, że problem leży po stronie serwera — ten wie o błędzie lub nie jest w stanie zrealizować żądania.
500 „Internal Server Error” — ogólny błąd serwera (nieobsłużone wyjątki, problemy z bazą, konfiguracją). Długotrwałe 500 szkodzi UX i SEO — wymaga priorytetowej analizy.
501 „Not Implemented” — serwer nie wspiera wymaganej funkcji. 502 „Bad Gateway” — brama/proxy dostała błędną odpowiedź od serwera nadrzędnego. 503 „Service Unavailable” — serwer chwilowo niedostępny (przeciążenie, prace serwisowe), zalecany Retry-After. 504 „Gateway Timeout” — brak odpowiedzi od upstream w zadanym czasie.
505 „HTTP Version Not Supported” — nieobsługiwana główna wersja HTTP. 507 „Insufficient Storage” — za mało miejsca na ukończenie żądania. 511 „Network Authentication Required” — wymagana autoryzacja sieciowa (np. captive portal).
Przypadki szczególne i kody specyficzne dla implementacji
Poza standardami IETF niektóre platformy definiują własne kody, przydatne w diagnozowaniu specyficznych problemów:
- Nginx – rozszerzenia 4xx: 444 „No Response” (zamyka połączenie bez odpowiedzi), 494 „Request Header Too Large”, 495 „SSL Certificate Error”, 499 „Client Closed Request”;
- Cloudflare – kody 5xx dla problemów origin/CDN: 530 „Origin DNS Error” (błąd rozwiązywania DNS), 540 „Temporarily Disabled” (czasowe wyłączenie endpointu);
- Shopify – historycznie 430 „Request Header Fields Too Large” (zastąpiony przez 429) i 783 „Unexpected Token” dla błędów składni JSON;
- Microsoft IIS – podkody dziesiętne doprecyzowujące bazowe 4xx (np. 404.1 „Site Not Found”, 404.2 „ISAPI or CGI Restriction”, 404.6 „Verb Denied”).
Najlepsze praktyki obsługi kodów statusu HTTP w REST API
Właściwy dobór i spójne stosowanie kodów statusu to fundament czytelnych, przewidywalnych REST API.
- Konsekwentne kody sukcesu – 200 „OK” dla odczytu/aktualizacji/usunięcia, 201 „Created” wyłącznie dla tworzenia z nagłówkiem Location wskazującym nowy zasób;
- Precyzyjna klasyfikacja błędów – zamiast ogólnego 500 używaj 400/401/403/404/422/429 wraz ze spójną strukturą odpowiedzi (kod, komunikat, szczegóły walidacyjne);
- Monitoring i alerting – analizuj rozkład 5xx (awarie), 401/403 (anomalie bezpieczeństwa), 429 (limity/przeciążenia) i reaguj automatycznie;
- Bezpieczna komunikacja błędów – przy 401/403 ograniczaj szczegóły; więcej informacji ujawniaj tylko uwierzytelnionym i uprawnionym klientom;
- Właściwe przekierowania – dla stałych zmian URL używaj 301 (GET) i 308 (inne metody); dla tymczasowych 302 (GET) i 307 (inne), aby uniknąć niepożądanych zmian metody;
- Centralna obsługa błędów – stosuj middleware (np. w Express) do jednolitego formatowania odpowiedzi i logowania.