To przeszukiwalne zestawienie wszystkich standardowych kodów statusu odpowiedzi HTTP z rejestru IANA, od <code>100 Continue</code> do <code>511 Network Authentication Required</code>. Każdy kod ma proste wyjaśnienie, wskazówki, kiedy serwer lub API powinny go wysłać, towarzyszące mu nagłówki odpowiedzi i link do definiującego go RFC. Popularne nieoficjalne kody — <code>499</code> z nginx, <code>419</code> z Laravel, <code>520</code>–<code>526</code> z Cloudflare — też są uwzględnione i wyraźnie oznaczone. Szukaj po numerze, nazwie lub słowie kluczowym, np. „redirect” albo „rate limit”.
Jak znaleźć kod statusu
- 1Wpisz kod (
404), jego początek (40), klasę (4xx), nazwę (teapot) lub słowo kluczowe (rate limit, cache, Retry-After). - 2Zawęź listę do jednej klasy filtrami 1xx–5xx albo ukryj kody nieoficjalne.
- 3Wybierz kod — myszą lub strzałkami — aby zobaczyć jego znaczenie, zastosowanie, powiązane nagłówki i specyfikację.
- 4Skopiuj kod lub całą linię statusu albo udostępnij adres strony: kończy się na
#404 i otwiera się od razu na tym kodzie.
Pięć klas kodów statusu
Klient, który otrzyma nieznany kod, traktuje go jak kod x00 jego klasy, więc nieznany 499 jest obsługiwany jak 400, a nieznany 299 jak 200. Dlatego nowe kody można wprowadzać bez psucia starszego oprogramowania.
- 1xx Informacyjne
- Odpowiedzi tymczasowe wysyłane przed ostateczną: 100 Continue, 101 Switching Protocols dla WebSocketów, 103 Early Hints do wstępnego ładowania.
- 2xx Sukces
- Żądanie się powiodło. 200 OK to domyślny kod; 201 Created i 204 No Content dokładniej mówią, co się stało.
- 3xx Przekierowanie
- Klient musi szukać gdzie indziej, zwykle pod adresem z nagłówka Location — albo, przy 304 Not Modified, użyć kopii z pamięci podręcznej.
- 4xx Błąd klienta
- Żądanie było błędne: źle sformułowane, nieuwierzytelnione, zabronione, dotyczące czegoś, co nie istnieje, lub zbyt częste. Ponowienie bez zmian nie pomoże.
- 5xx Błąd serwera
- Żądanie mogło być poprawne, ale zawiódł serwer lub coś za nim. Często są to błędy przejściowe i warto ponowić próbę z rosnącym odstępem (back-off).
Jak dobrać właściwy kod dla API
Większości API wystarczy kilkanaście kodów. Dla sukcesu: 200 z treścią, 201 z nagłówkiem Location, gdy coś utworzono, 202, gdy przetwarzanie nastąpi później, i 204, gdy nie ma czego zwrócić. Dla błędów klienta: 400 dla źle sformułowanych żądań, 422 dla poprawnie sformułowanych danych, które nie przechodzą walidacji, 401, gdy brakuje danych uwierzytelniających lub są nieprawidłowe, 403, gdy są prawidłowe, ale niewystarczające, 404 dla nieznanych zasobów, 409 dla konfliktów, np. zduplikowanego e-maila, i 429 przy limitowaniu żądań. Dla błędów serwera: 500 dla błędów w kodzie oraz 502, 503 i 504 dla awarii infrastruktury pośredniej.
Niezależnie od kodu zwracaj treść, która go wyjaśnia. RFC 9457 „Problem Details” (application/problem+json) nadaje jej standardową postać z polami type, title, status i detail. Nigdy nie zwracaj 200 z błędem w treści: cache, monitoring i logika ponowień czytają kod statusu, a nie Twój JSON. Do sformatowania takiej treści użyj formatera JSON.
Kody, które często się myli
- 401 vs 403
- 401 Unauthorized oznacza „nie wiem, kim jesteś”: zaloguj się lub wyślij prawidłowy token. 403 Forbidden oznacza „wiem, kim jesteś, i nie możesz tego zrobić”.
- 301 vs 302 vs 307 vs 308
- 301 i 308 są stałe i przenoszą pozycję w wyszukiwarce na nowy URL; 302 i 307 są tymczasowe. 307 i 308 gwarantują zachowanie metody i treści, a przy 301 i 302 przeglądarki zamieniają POST na GET.
- 400 vs 422
- 400 dotyczy żądań, których serwer w ogóle nie potrafi sparsować; 422 poprawnego JSON-a, którego zawartość łamie reguły, np. brakuje wymaganego pola.
- 404 vs 410
- 404 mówi, że teraz nic tu nie ma; 410 — że coś tu było i zostało celowo usunięte, przez co wyszukiwarki szybciej to usuwają z indeksu.
- 502 vs 504
- Oba pochodzą od proxy lub load balancera. 502 oznacza, że serwer upstream odpowiedział czymś nieprawidłowym lub zamknął połączenie; 504 — że nie odpowiedział na czas.
- 500 vs 503
- 500 to nieoczekiwana awaria, zwykle błąd w kodzie. 503 to znany, przejściowy stan — prace serwisowe lub przeciążenie — i powinien zawierać Retry-After.
Kody statusu a SEO
Wyszukiwarki uważnie czytają kody statusu. Używaj 301 lub 308, gdy strona przenosi się na stałe, aby jej pozycja przeniosła się razem z nią; 302 mówi im, że indeksować należy nadal stary URL. Dla brakujących stron zwracaj prawdziwy 404 lub 410 — strona „nie znaleziono” zwracająca 200 to „soft 404”, która marnuje budżet indeksowania. Podczas prac serwisowych zwracaj 503 z Retry-After, aby strony nie wypadły z indeksu. Określ, co mogą odwiedzać roboty, w generatorze robots.txt.
Odpowiedzi z kodami 200, 203, 204, 206, 300, 301, 308, 404, 405, 410, 414, 451 i 501 mogą być buforowane przez przeglądarki i CDN nawet bez jawnych nagłówków świeżości, więc przypadkowy 404 lub 301 może się długo utrzymywać; ustawiaj dla nich Cache-Control świadomie.
Nieoficjalne kody, które zobaczysz w logach
Niektórych kodów nie ma w rejestrze IANA, ale są powszechne w praktyce. nginx zapisuje 499, gdy klient rozłączy się przed odpowiedzią, i 444, gdy sam zamknął połączenie bez odpowiedzi. Cloudflare zwraca 520–526, gdy nie może uzyskać poprawnej odpowiedzi od serwera źródłowego: 521 oznacza, że źródło odrzuciło połączenie, 522 — przekroczenie czasu, 524 — odpowiedź trwała ponad 100 sekund, a 525/526 — nieudane połączenie TLS ze źródłem. Laravel wysyła 419, gdy token CSRF wygasł. Na liście są one oznaczone jako „nieoficjalne” i można je ukryć.
- Czym jest kod statusu HTTP?
- To trzycyfrowa liczba na początku każdej odpowiedzi HTTP, która mówi klientowi, jak poszło żądanie. Pierwsza cyfra określa klasę: 1xx informacyjne, 2xx sukces, 3xx przekierowanie, 4xx błąd klienta i 5xx błąd serwera.
- Czym różni się 401 od 403?
- 401 Unauthorized oznacza, że żądanie nie ma prawidłowych danych uwierzytelniających, więc zalogowanie może pomóc. 403 Forbidden oznacza, że serwer wie, kim jesteś, ale nie masz uprawnień, więc ponowne logowanie nie pomoże.
- Użyć 301 czy 302 do przekierowania?
- Użyj 301 (lub 308), gdy przeniesienie jest stałe, np. przy zmianie URL lub migracji domeny; wyszukiwarki przenoszą pozycję strony na nowy adres. Użyj 302 (lub 307), gdy oryginalny URL jeszcze wróci.
- Co oznacza 429 Too Many Requests?
- Klient trafił na limit żądań. Odczekaj przed ponowieniem: nagłówek Retry-After, jeśli jest obecny, podaje liczbę sekund lub godzinę. Klienci powinni wydłużać odstępy wykładniczo zamiast ponawiać od razu.
- Co powoduje błąd 502 Bad Gateway?
- Proxy, load balancer lub CDN przed stroną otrzymał nieprawidłową odpowiedź od serwera za nim — zwykle dlatego, że aplikacja się zawiesiła, zrestartowała lub zamknęła połączenie. Naprawa jest po stronie serwera, w logach aplikacji upstream.
- Czym jest kod statusu 499?
- To kod specyficzny dla nginx, zapisywany, gdy klient zamknął połączenie, zanim nginx zdążył wysłać odpowiedź. Klient nigdy go nie otrzymuje. Wiele kodów 499 zwykle oznacza, że backend jest zbyt wolny i klienci rezygnują.
- Czy 418 I'm a teapot to prawdziwy kod statusu?
- Powstał jako żart primaaprilisowy w RFC 2324 (1998). Nie jest przeznaczony do realnego użytku, ale ponieważ implementuje go mnóstwo oprogramowania, RFC 9110 rezerwuje kod 418, by nigdy nie przypisano go do niczego innego.
- Ile jest kodów statusu HTTP?
- Rejestr IANA definiuje około 63 kodów, w tym kilka zarezerwowanych lub przestarzałych, jak 306 i 305. Możliwe są kody od 100 do 599, a każdy nieznany kod klienci traktują jak kod x00 jego klasy.
