Kody statusu HTTP
Kody najczęściej widywane w API i CDN. Rzadkie eksperymentalne pominięto.
| Kod | Nazwa | Znaczenie |
|---|---|---|
| 200 | OK | Powodzenie z treścią |
| 201 | Utworzono | Utworzono zasób |
| 204 | Brak treści | Powodzenie, pusta treść |
| 301 | Przeniesiono trwale | Trwałe przekierowanie |
| 302 | Znaleziono | Przejściowe przekierowanie |
| 304 | Nie zmodyfikowano | Użyj kopii z cache |
| 400 | Nieprawidłowe żądanie | Nieprawidłowe żądanie klienta |
| 401 | Nieautoryzowano | Wymagana autoryzacja lub nieudana |
| 403 | Zabronione | Uwierzytelniono, ale odmówiono |
| 404 | Nie znaleziono | Zasób nie istnieje |
| 405 | Metoda niedozwolona | Zła metoda HTTP |
| 408 | Upłynął czas żądania | Klient zbyt wolny |
| 409 | Konflikt | Konflikt stanu |
| 410 | Usunięto ostatecznie | Trwale usunięto |
| 422 | Nieprzetwarzalna jednostka | Nieprawidłowa semantyka |
| 429 | Zbyt wiele żądań | Ograniczenie częstotliwości |
| 500 | Wewnętrzny błąd serwera | Awaria serwera |
| 502 | Zła bramka | Nieprawidłowa odpowiedź upstream |
| 503 | Usługa niedostępna | Przeciążony lub niedostępny |
| 504 | Przekroczono czas bramki | Upstream przekroczył czas |
Uwagi
- 401 vs 403: brak/nieudane logowanie kontra zalogowany bez uprawnień.
- CDN może zwrócić 5xx, gdy origin jest niedostępny.
Pięć klas kodów statusu
Pierwsza cyfra mówi, kto ponosi odpowiedzialność i przybliża przyczynę zdarzenia. Kody 1xx to odpowiedzi informacyjne, rzadko widywane przez klienta. 2xx oznaczają sukces — 200 OK z ciałem odpowiedzi, 204 No Content bez ciała, 206 dla częściowego pobrania. 3xx oznaczają, że zasób znajduje się w innym miejscu. 4xx wskazują na błąd samego żądania: złą składnię, brak danych uwierzytelniających lub przekroczenie limitu szybkości. 5xx oznaczają, że serwer nie pomyślnie obsłużył poprawne żądanie. Sam już pierwszy cyfra mówi, czy naprawiać klienta, czy zgłaszać problem po stronie serwera.
Wybór odpowiedniego przekierowania
301 i 308 oznaczają trwałość; 302 i 307 oznaczają czasowość. Różnica polega na obsłudze metody HTTP: 301 i 302 historycznie pozwalają klientowi zamienić POST na GET, podczas gdy 307 i 308 zachowują oryginalną metodę i ciało żądania, co ma znaczenie dla API i przesyłania formularzy. Używaj 301 dla URL, które na stałe się przesunął, a 302 lub 307 dla tymczasowego routingu, np. stron konserwacyjnych czy testów A/B. Uwaga na łańcuchy przekierowań — każde dodatkowe przepięcie kosztuje opóźnienie i autorytet linków, więc przekierowuj bezpośrednio do ostatecznego celu.
Rozróżnianie błędów 4xx
401 oznacza brak lub niepowodzenie uwierzytelnienia, więc przesłanie ważnych danych logowania może rozwiązać problem; 403 oznacza, że żądanie zostało zrozumiane i uwierzytelnione, ale nie zostało dopuszczone — ponowienie z tymi samymi danymi nie pomoże. 404 oznacza, że zasób nie istnieje; 410 sygnalizuje, że istniał, ale został celowo usunięty. 429 oznacza przekroczenie limitu szybkości — należy zwolnić tempa, respektując nagłówek Retry-After. 400 zwykle oznacza złą formę danych, 405 oznacza niewłaściwą metodę dla danego URL, a 422 oznacza, że składnia była poprawna, lecz zawartość nie przeszła walidacji.
Analiza kodów 5xx
500 to ogólny błąd wewnętrzny; 502 Bad Gateway oznacza, że serwer upstream zwrócił coś nieużywalnego; 503 oznacza, że usługa jest chwilowo niedostępna lub przeciążona; 504 oznacza, że upstream nie odpowiedział w wyznaczonym czasie. To problemy serwera, nie wywołującego, więc rozwiązaniem jest ponawianie z backoffem, sprawdzenie stanu upstream lub odciążenie ruchu. CDN może zwracać 502, 503 lub 504 w imieniu origin, którego nie może dotrzeć, dlatego ten sam błąd może pochodzić z dwóch zupełnie różnych miejsc — sprawdź nagłówki server i cache-status, aby ustalić źródło.
Kody statusu w praktyce: API i buforowanie
Dwa codzienne zastosowania szczególnie warto przeanalizować. Po pierwsze buforowanie: 200 z nagłówkiem Cache-Control może być przechowywane, 304 Not Modified instruuję klienta, by użył swojej kopii, a 5xx nie powinno być buforowane. Po drugie API: POST tworzący zasób powinien zwracać 201 z nagłówkiem Location, DELETE często zwraca 204, a PATCH, który nic nie zmienia, może zwrócić 200 lub 204. Dobrze zaprojektowani klienci najpierw rozróżniają klasę kodu (2xx, 4xx, 5xx), a dopiero potem dokładny kod, dzięki czemu logika ponawiania i backoffu pozostaje prosta i przewidywalna.
Częste pytania
- Co oznacza kod HTTP 403?
- 403 oznacza, że serwer zrozumiał i uwierzytelnił żądanie, ale odmawia dostępu do zasobu. W przeciwieństwie do 401 ponowne logowanie nie pomoże.
- Jaka jest różnica między przekierowaniami HTTP 301 i 302?
- 301 to przekierowanie stałe — klienci i wyszukiwarki powinny używać nowego adresu URL. 302 jest tymczasowe, a stary adres pozostaje ważny.
- Co oznacza HTTP 429 i jak to naprawić?
- 429 oznacza osiągnięcie limitu żądań. Zwolnij i stosuj się do nagłówka Retry-After, jeśli serwer go zwraca.