Referencja Kodów Stanu HTTP

Referencja Kodów Stanu HTTP to kompletny, przeszukiwalny indeks każdego kodu stanu zdefiniowanego w specyfikacjach HTTP — od 100 Continue aż do 511 Network Authentication Required. Każdy wpis przedstawia kanoniczną nazwę, definicję RFC, co dany kod rzeczywiście oznacza, kiedy go wysyłać, kiedy nie wysyłać oraz typowe pułapki, które mogą sprawiać problemy w realnych projektach. Filtr działający na żywo oraz kafelki kategorii pozwalają przeskakiwać między klasami za pomocą jednego kliknięcia.

W przeciwieństwie do zwykłych, płaskich list, to narzędzie daje każdemu kodowi jego własną mikro-stronę z trzema wyróżnionymi kolorystycznie sekcjami (używaj / nie używaj / pułapki) oraz gotowymi do wklejenia handlerami dla Express.js, Django, FastAPI i Go net/http. Animowany diagram połączenia pokazuje drogę żądania od klienta do serwera oraz powracający wybrany status — co jest niezwykle przydatne dla osób początkujących, które uczą się, co kod stanu reprezentuje w sieci.

Dlaczego referencja kodów stanu jest ważna

Jak korzystać z Referencji Kodów Stanu HTTP

1. Szybkie wyszukiwanie. Wpisz kod (404) lub fragment nazwy (teapot, gateway) w pole wyszukiwania na górze i zatwierdź. Dopasowany wpis otworzy się z pełnym panelem szczegółów.
2. Przeglądanie według klas. Kliknij dowolny z 5 kafelków (1xx, 2xx, 3xx, 4xx, 5xx), aby przefiltrować siatkę do wybranej klasy. Kliknij Wszystkie, aby zresetować filtr.
3. Filtr na żywo. Pole filtrowania tuż nad siatką zawęża widoczne karty podczas pisania — przydatne, gdy pamiętasz tylko część nazwy, np. too many lub precondition.
4. Sprawdź kod. Kliknij dowolną kartę, aby otworzyć panel szczegółów. Zobaczysz tam znaczenie, kiedy używać, kiedy nie używać, typowe pułapki oraz blok z kodem dla 4 frameworków.
5. Skopiuj fragment kodu. Użyj przełącznika zakładek i małego przycisku Kopiuj, aby pobrać gotowy do wklejenia handler.
6. Porównaj sąsiadów. Panel szczegółów kończy się kartami rodzeństwa z tej samej klasy (1xx / 2xx / 3xx / 4xx / 5xx) w celu szybkiego bezpośredniego porównania.

Pięć klas statusów HTTP w skrócie

Często mylone pary

• 401 vs 403. 401 oznacza nieuwierzytelniony — żądanie nie zawiera prawidłowych poświadczeń. 403 oznacza uwierzytelniony, ale nieuprawniony — poświadczenia są poprawne, ale użytkownik nie ma wymaganych praw dostępu.
• 404 vs 410. 404 oznacza nieznany: być może istnieje gdzieś indziej, a być może to literówka. 410 oznacza celowo usunięty: wyszukiwarki powinny usunąć ten adres ze swojego indeksu.
• 301 vs 302 vs 307 vs 308. 301 / 308 są stałe (308 rygorystycznie zachowuje metodę i treść żądania), natomiast 302 / 307 są tymczasowe (307 rygorystycznie zachowuje metodę i treść). Używaj 307 / 308 do przekierowań POST / PUT / PATCH.
• 400 vs 422. 400 oznacza, że treść żądania jest uszkodzona (błędny JSON, brakujące pole). 422 oznacza, że treść została poprawnie sparsowana, ale wartości nie spełniają reguł biznesowych (nieprawidłowy format e-mail, ilość poza zakresem).
• 502 vs 503 vs 504. 502 oznacza, że serwer nadrzędny przesłał nieprawidłowe dane. 503 oznacza, że serwer jest przeciążony lub wyłączony na czas konserwacji. 504 oznacza, że serwer nadrzędny nie odpowiedział w oczekiwanym czasie.
• 409 vs 412. 409 to konflikt z obecnym stanem zasobu. 412 oznacza konkretnie, że nagłówek warunku wstępnego (If-Match, If-Unmodified-Since) zwrócił fałsz.

Nagłówki łączone z konkretnymi kodami stanu

• 201 Created — powinien zawierać nagłówek Location wskazujący na nowy zasób.
• 301 / 302 / 307 / 308 — muszą zawierać nagłówek Location z docelowym URL.
• 304 Not Modified — musi powtórzyć nagłówki, które pojawiłyby się przy kodzie 200 (ETag, Cache-Control, Vary).
• 401 Unauthorized — musi zawierać nagłówek WWW-Authenticate wymieniający akceptowane schematy (Basic, Bearer).
• 405 Method Not Allowed — musi zawierać nagłówek Allow wymieniający metody, które są dozwolone.
• 413 / 429 / 503 — często zawierają nagłówek Retry-After (w sekundach lub jako HTTP-date), aby klienci mogli ponowić próbę po odpowiednim czasie.
• 416 Range Not Satisfiable — musi zawierać nagłówek Content-Range: bytes */<length>.

Kody stanu, które prawie zawsze możesz zignorować

Kilka kodów jest technicznie poprawnych, lecz niezwykle rzadkich we współczesnych API: 305 Use Proxy (wycofany), 306 (zarezerwowany, nieużywany), 305, 506 Variant Also Negotiates, 510 Not Extended oraz 508 Loop Detected. Większość z nich jest utrzymywana w rejestrze ze względów historycznych. Jeśli Twoja biblioteka lub warstwa pośrednia (middleware) zwraca jeden z nich, potraktuj to jako zgłoszenie błędu w bibliotece — a nie wskazówkę, aby obsługiwać go w specjalny sposób.

FAQ

Czy narzędzie zawiera kody z dokumentów RFC innych niż 9110?

Tak. Obejmuje ono RFC 9110 (semantyka HTTP), RFC 6585 (dodatkowe kody 4xx / 5xx), RFC 4918 (WebDAV), RFC 5842 (powiązania WebDAV), RFC 7725 (451), RFC 8297 (103 Early Hints), RFC 8470 (425 Too Early) oraz słynny, żartobliwy RFC 2324 (418 Teapot).

Czy te kody są poprawne w HTTP/2 i HTTP/3?

Tak. Semantyka kodów stanu jest zdefiniowana w RFC 9110, który jest dokumentem semantyki HTTP niezależnym od wersji. HTTP/2 (RFC 9113) i HTTP/3 (RFC 9114) zmieniają jedynie ramkowanie i kwestie transportowe.

Czy mogę linkować bezpośrednio do konkretnego kodu?

Zatwierdź formularz z pojedynczym kodem (na przykład 404), a panel szczegółów załaduje się pod formularzem. Adres URL będzie zawierał Twoje zapytanie i można go bezpiecznie udostępniać — otwarcie go załaduje ten sam wynik.

Dlaczego mój framework nie pozwala mi zwrócić kodu 418?

Starsze wersje niektórych bibliotek HTTP odmawiają zwracania kodów, których nie ma w ich wewnętrznym rejestrze. Rozwiązaniem jest aktualizacja biblioteki lub, jeśli to możliwe, ręczne zapisanie linii statusu.

Czy API powinno kiedykolwiek zwracać kod 200 z informacją o błędzie w treści?

Nie. Systemy monitorujące, mechanizmy ponawiania prób i serwery pośredniczące zakładają, że klasa 2xx oznacza sukces. Jeśli musisz zwrócić strukturę błędu, użyj odpowiedniego kodu 4xx lub 5xx, a szczegóły umieść wewnątrz treści odpowiedzi. Format Problem Details dla HTTP API (RFC 9457) stanowi tutaj dobry wzorzec.

Czy istnieje oficjalny rejestr kodów stanu HTTP?

Tak. Organizacja IANA prowadzi oficjalny rejestr pod adresem iana.org/assignments/http-status-codes. To narzędzie pozostaje zsynchronizowane z tym rejestrem oraz z najczęściej cytowanymi dokumentami RFC.