Kody statusu HTTP
Wszystkie kody statusu HTTP z opisem, co oznaczają i kiedy ich używać.
O tym narzędziu
Wyszukaj dowolny kod statusu HTTP po numerze lub nazwie. Każdy ma prosty opis i wskazówkę, kiedy go zwracać, co pomaga przy projektowaniu API lub analizie nieudanego żądania.
Jak z tego korzystać
- Wpisz kod statusu, np. 404, albo słowo, np. redirect lub rate limit.
- Filtruj według klasy: 1xx informacyjne, 2xx sukces, 3xx przekierowania, 4xx błędy klienta, 5xx błędy serwera.
- Przeczytaj, co oznacza każdy kod i kiedy go zwracać.
Pytania
- Czym różni się 401 od 403?
- 401 oznacza, że klient nie jest uwierzytelniony, np. brakuje tokenu albo token wygasł. 403 oznacza, że klient jest uwierzytelniony, ale nie ma uprawnień do tej operacji.
- Czy błędy walidacji powinny zwracać 400 czy 422?
- Używa się obu. Częsta konwencja to 400 dla żądań, których nie da się sparsować, i 422 dla poprawnie zbudowanych żądań, których wartości nie przechodzą walidacji.
- Kiedy używać 301, a kiedy 308?
- Oba to przekierowania stałe. Przy 301 przeglądarki mogą zamienić POST na GET; 308 gwarantuje zachowanie metody i treści. Przy zwykłym przeniesieniu strony 301 w zupełności wystarczy.
- Czym różni się 502 od 504?
- Oba pochodzą od proxy lub load balancera. 502 oznacza, że serwer za nim zwrócił nieprawidłową odpowiedź lub uległ awarii; 504 – że nie odpowiedział na czas.
- Co oznacza kod statusu 0?
- To nie jest status HTTP. Przeglądarki zgłaszają 0, gdy do skryptu nie dotarła żadna odpowiedź: żądanie zostało zablokowane przez CORS, anulowane, trafiło na błąd sieci lub DNS albo zablokowano je jako mixed content. Prawdziwą przyczynę znajdziesz w konsoli przeglądarki i na karcie Network.
- Czy można zwrócić 404 zamiast 403?
- Tak. RFC 9110 pozwala serwerowi odpowiedzieć 404, gdy nie chce ujawniać istnienia zasobu komuś, kto może nie mieć do niego wglądu. GitHub robi tak w przypadku prywatnych repozytoriów. Używaj 403, gdy klient może wiedzieć, że zasób istnieje, ale nie ma do niego dostępu.
- Które kody statusu mogą być domyślnie cache'owane?
- Zgodnie z RFC 9110 odpowiedzi z kodami 200, 203, 204, 206, 300, 301, 308, 404, 405, 410, 414 i 501 mogą być cache'owane heurystycznie, gdy żaden nagłówek Cache-Control ani Expires nie mówi inaczej. Dlatego CDN może jeszcze przez jakiś czas serwować 404. Aby to kontrolować, wysyłaj jawne nagłówki cache.
Co to są kody statusu HTTP?
Każda odpowiedź HTTP zaczyna się od trzycyfrowego kodu statusu, który mówi klientowi, jak poszło żądanie. Kody i ich znaczenia definiuje RFC 9110, a kilka dodały inne RFC, np. 429 Too Many Requests z RFC 6585. Pierwsza cyfra wyznacza klasę: 1xx informacyjne, 2xx sukces, 3xx przekierowanie, 4xx błąd klienta i 5xx błąd serwera. Klient, który nie zna danego kodu, traktuje go jak kod x00 z jego klasy.
Większość oprogramowania reaguje właśnie na klasę. Przeglądarki podążają za przekierowaniami 3xx, logika ponawiania zwykle ponawia niektóre odpowiedzi 5xx, ale nigdy większości 4xx, a monitoring liczy 5xx jako błędy po Twojej stronie. Tekst po liczbie (reason phrase), np. „Not Found”, ma charakter wyłącznie informacyjny, a HTTP/2 w ogóle go pomija. Dlatego wybór właściwej liczby ma większe znaczenie niż komunikat, który do niej dołączasz.
Jaki kod statusu HTTP powinno zwracać moje API?
Zacznij od typowych przypadków. Zwracaj 200 przy udanym odczycie lub aktualizacji z treścią odpowiedzi, 201 z nagłówkiem Location, gdy POST coś tworzy, i 204, gdy nie ma nic do odesłania, np. po DELETE. Użyj 202, gdy praca trafia do kolejki i kończy się później. Unikaj zwracania 200 z komunikatem błędu w treści: klienty, cache i narzędzia monitorujące ufają przede wszystkim kodowi statusu.
W przypadku błędów oddziel winę klienta od swojej. Używaj 400 dla błędnie sformułowanych danych, 404, gdy zasób nie istnieje, 409 dla konfliktów, takich jak zduplikowany adres e-mail, i 429 z nagłówkiem Retry-After dla limitów zapytań. 5xx zostaw dla awarii po stronie serwera i loguj szczegóły zamiast zwracać stack trace. Spójny format błędów, np. Problem Details z RFC 9457, pomaga klientom wyświetlać przydatne komunikaty.
Jak sprawdzić kod statusu żądania?
W przeglądarce otwórz narzędzia deweloperskie, przejdź na kartę Network (Sieć) i przeładuj stronę. Kolumna Status pokazuje kod każdego żądania, łącznie z nieudanymi wywołaniami fetch wykonanymi przez skrypty. W wierszu poleceń curl -i wypisuje linię statusu i nagłówki odpowiedzi przed treścią, curl -I wysyła żądanie HEAD, aby pokazać same nagłówki, a dodanie -L sprawia, że curl podąża za przekierowaniami, więc widzisz każdy przeskok.
Gdy kod Cię zaskakuje, ustal, kto go wysłał. 502, 503 albo 504 często pochodzi od nginx, load balancera lub CDN-a, a nie od Twojej aplikacji, więc sprawdź nagłówek Server i logi proxy. 404 na trasie, o której wiesz, że istnieje, zwykle oznacza złą ścieżkę bazową albo niezgodność ukośnika na końcu, a 405 oznacza, że ścieżka istnieje, ale nie dla tej metody. Kreator i konwerter poleceń curl pomoże odtworzyć nieudane żądanie.
Wszystkie kody statusu HTTP
Wszystkie kody statusu z opisem, co oznaczają i kiedy je zwracać, pogrupowane według klas.
Informacyjne (1xx)
| Kod | Nazwa | Znaczenie | Kiedy używać |
|---|---|---|---|
| 100 | Continue | Serwer otrzymał nagłówki żądania; klient powinien wysłać treść. | Wysyłany automatycznie, gdy klient pyta nagłówkiem Expect: 100-continue. |
| 101 | Switching Protocols | Serwer przełącza się na protokół, o który prosił klient. | Przełączenie połączenia na WebSocket. |
| 103 | Early Hints | Wstępne nagłówki, aby przeglądarka mogła zacząć wczytywać zasoby z wyprzedzeniem. | Wysyłaj nagłówki Link dla CSS i czcionek, gdy strona jest jeszcze budowana. |
Sukces (2xx)
| Kod | Nazwa | Znaczenie | Kiedy używać |
|---|---|---|---|
| 200 | OK | Żądanie zakończyło się powodzeniem. | Domyślny dla udanego GET lub POST, który zwraca wynik. |
| 201 | Created | Utworzono nowy zasób. | Po żądaniu POST, które coś tworzy. Dołącz nagłówek Location wskazujący nowy zasób. |
| 202 | Accepted | Żądanie zostało przyjęte, ale jeszcze nie zostało przetworzone. | Zadania w kolejce lub w tle. Zwróć sposób na sprawdzenie postępu. |
| 204 | No Content | Sukces, bez treści do odesłania. | DELETE lub PUT, które nie zwraca treści. |
| 206 | Partial Content | Zwracana jest tylko część zasobu. | Odpowiedź na żądanie Range, np. przy streamingu wideo lub wznawianym pobieraniu. |
Przekierowanie (3xx)
| Kod | Nazwa | Znaczenie | Kiedy używać |
|---|---|---|---|
| 301 | Moved Permanently | Zasób ma nowy, stały URL. | Stare URL-e po przebudowie serwisu. Przeglądarki i wyszukiwarki to zapamiętują. |
| 302 | Found | Zasób jest tymczasowo pod innym URL-em. | Krótkotrwałe przekierowania. Klient może zmienić POST na GET; aby było jednoznacznie, wybierz 303 lub 307. |
| 303 | See Other | Pobierz wynik z innego URL-a za pomocą GET. | Przekierowanie po wysłaniu formularza metodą POST, aby odświeżenie strony nie wysłało go ponownie. |
| 304 | Not Modified | Kopia w pamięci podręcznej jest wciąż aktualna. | Odpowiedź na żądanie warunkowe z If-None-Match lub If-Modified-Since. |
| 307 | Temporary Redirect | Powtórz to samo żądanie pod innym URL-em. | Tymczasowe przekierowanie, które musi zachować metodę i treść. |
| 308 | Permanent Redirect | Powtórz to samo żądanie pod nowym, stałym URL-em. | Jak 301, ale metoda i treść nie mogą się zmienić. |
Błąd klienta (4xx)
| Kod | Nazwa | Znaczenie | Kiedy używać |
|---|---|---|---|
| 400 | Bad Request | Żądanie jest zniekształcone lub nieprawidłowe. | JSON, którego nie da się sparsować, brakujące wymagane pola, nieprawidłowe typy. |
| 401 | Unauthorized | Brak uwierzytelnienia lub jest ono nieprawidłowe. | Brak tokenu lub token wygasł. Mimo nazwy oznacza „nieuwierzytelniony”. |
| 402 | Payment Required | Zarezerwowany; niektóre API używają go przy problemach z płatnościami. | Osiągnięto limit planu lub płatność się nie powiodła. |
| 403 | Forbidden | Klient jest znany, ale nie ma uprawnień do tej operacji. | Zalogowany, ale bez uprawnień. |
| 404 | Not Found | Pod tym URL-em nic nie istnieje. | Nieznane ścieżki lub ID. Używany też do ukrywania zasobów, o których klient może nie wiedzieć. |
| 405 | Method Not Allowed | Ten URL nie obsługuje tej metody HTTP. | POST do endpointu tylko do odczytu. Dołącz nagłówek Allow. |
| 406 | Not Acceptable | Żadna reprezentacja nie pasuje do nagłówka Accept. | Klient poprosił o XML z API obsługującego tylko JSON. |
| 408 | Request Timeout | Klient zbyt długo wysyłał żądanie. | Bezczynne połączenia. Klient może bezpiecznie ponowić żądanie. |
| 409 | Conflict | Żądanie jest sprzeczne z bieżącym stanem. | Zduplikowane wartości unikalne albo edycja oparta na nieaktualnej wersji. |
| 410 | Gone | Zasób istniał, ale został trwale usunięty. | Usunięta treść lub wycofane wersje API. Mocniejsze niż 404. |
| 411 | Length Required | Wymagany jest nagłówek Content-Length. | Przesyłanie bez zadeklarowanego rozmiaru. |
| 412 | Precondition Failed | Nagłówek warunkowy nie został spełniony. | If-Match z nieaktualnym ETagiem, aby zapobiec utracie aktualizacji. |
| 413 | Content Too Large | Treść żądania jest większa, niż serwer akceptuje. | Przesyłane pliki przekraczające limit rozmiaru. |
| 414 | URI Too Long | URL jest dłuższy, niż serwer jest w stanie obsłużyć. | Ogromne query stringi. Przenieś dane do treści żądania POST. |
| 415 | Unsupported Media Type | Format treści nie jest obsługiwany. | Wysyłanie danych formularza do endpointu JSON albo nieprawidłowy Content-Type. |
| 416 | Range Not Satisfiable | Żądany zakres bajtów wykracza poza plik. | Żądanie Range wykraczające poza koniec zasobu. |
| 418 | I’m a teapot | Primaaprilisowy żart z 1998 roku, który się przyjął. | Tylko jako easter egg. |
| 422 | Unprocessable Content | Żądanie jest poprawnie zbudowane, ale nie przechodzi walidacji. | Prawidłowy JSON z nieprawidłowymi wartościami, np. datą końcową wcześniejszą niż początkowa. |
| 423 | Locked | Zasób jest zablokowany. | WebDAV albo rekord edytowany przez kogoś innego. |
| 425 | Too Early | Serwer nie zaryzykuje przetworzenia żądania, które mogło zostać powtórzone. | Wczesne dane TLS (0-RTT). |
| 426 | Upgrade Required | Klient musi przełączyć się na inny protokół. | Wymuszenie nowszej wersji TLS lub HTTP. |
| 428 | Precondition Required | Żądanie musi być warunkowe. | Wymaganie If-Match przy aktualizacjach, aby uniknąć utraty zapisów. |
| 429 | Too Many Requests | Klient wysyła żądania zbyt szybko. | Ograniczanie liczby żądań (rate limiting). Dołącz nagłówek Retry-After. |
| 431 | Request Header Fields Too Large | Nagłówki są za duże. | Zwykle winne są zbyt duże pliki cookie. |
| 451 | Unavailable For Legal Reasons | Zablokowano z powodów prawnych. | Treść usunięta nakazem sądowym lub zablokowana w danym kraju. |
Błąd serwera (5xx)
| Kod | Nazwa | Znaczenie | Kiedy używać |
|---|---|---|---|
| 500 | Internal Server Error | Coś poszło nie tak na serwerze. | Nieobsłużone wyjątki. Zapisz szczegóły w logach, ale nie ujawniaj ich klientowi. |
| 501 | Not Implemented | Serwer nie obsługuje tej funkcji. | Metoda HTTP, której serwer w ogóle nie rozpoznaje. |
| 502 | Bad Gateway | Proxy otrzymało nieprawidłową odpowiedź od serwera, który za nim stoi. | Aplikacja za nginx lub load balancerem uległa awarii albo zwróciła śmieci. |
| 503 | Service Unavailable | Serwer nie może teraz obsługiwać żądań. | Prace serwisowe lub przeciążenie. Dołącz Retry-After, jeśli wiesz, kiedy usługa wróci. |
| 504 | Gateway Timeout | Proxy nie otrzymało odpowiedzi na czas. | Aplikacja docelowa jest zbyt wolna lub się zawiesiła. |
| 505 | HTTP Version Not Supported | Ta wersja HTTP nie jest obsługiwana. | Rzadki; bardzo stare lub bardzo nowe wersje protokołu. |
| 507 | Insufficient Storage | Serwer nie ma miejsca na zapisanie wyniku. | Pełny dysk lub osiągnięty limit miejsca. |
| 508 | Loop Detected | Serwer wykrył nieskończoną pętlę podczas przetwarzania. | WebDAV albo pętla przekierowań lub proxy. |
| 511 | Network Authentication Required | Klient musi się zalogować, aby uzyskać dostęp do sieci. | Portale logowania (captive portal) w sieciach Wi-Fi hoteli i lotnisk. |
Coś nie działa albo wynik wygląda na błędny? Zgłoś problem z tym narzędziem