Kody statusu HTTP to trzycyfrowe liczby, które serwer zwraca na początku każdej odpowiedzi, aby podsumować, co się stało. Na ich podstawie przeglądarki, klienci, serwery proxy i sieci CDN decydują, czy zapisać odpowiedź w cache, przekierować, ponowić próbę, czy pokazać użytkownikowi błąd.
Każdy kod statusu należy do jednej z pięciu klas wyznaczanych przez pierwszą cyfrę: 1xx informacyjne, 2xx sukces, 3xx przekierowanie, 4xx błąd klienta, 5xx błąd serwera. Gdy znasz klasę, zwykle znasz też ogólne znaczenie, zanim jeszcze sprawdzisz konkretny kod.
Większość aplikacji korzysta tylko z niewielkiego zestawu (200, 201, 204, 301, 302, 304, 400, 401, 403, 404, 409, 422, 429, 500, 502, 503). Wiedza, co każdy z nich *oznacza*, oraz różnica między 401 Unauthorized a 403 Forbidden czy 301 Moved Permanently a 302 Found, czyni cię lepszym programistą backendu i API.
Czego nauczysz się, korzystając z tej listy
Pierwsza cyfra zawsze wskazuje klasę: 1xx informacja, 2xx sukces, 3xx przekierowanie, 4xx błąd klienta, 5xx błąd serwera.
Kody statusu są *częścią kontraktu* API: klienci powinni podejmować decyzje na ich podstawie, a nie wyciągać komunikaty o błędach z treści odpowiedzi.
4xx oznacza, że klient zrobił coś źle (błędne dane, brak uwierzytelnienia, brak zasobu). 5xx oznacza, że zawiódł serwer, niezależnie od tego, co zrobił klient.
Niektóre kody mają subtelne różnice: 401 vs 403, 301 vs 308, 200 vs 204. Te rozróżnienia mają znaczenie dla cache i ponawiania prób.
Jak korzystać z listy kodów HTTP krok po kroku
1
Szukaj po kodzie lub nazwie
Wpisz liczbę (404, 429) lub słowo kluczowe (auth, redirect, rate limit), a pasujące kody odfiltrują się na bieżąco.
2
Filtruj według klasy
Użyj przycisków klas (1xx, 2xx, 3xx, 4xx, 5xx), aby zawęzić listę, gdy przeglądasz, zamiast szukać.
3
Przeczytaj proste wyjaśnienie
Każdy wpis mówi, kiedy kod jest wysyłany, jak zwykle zachowuje się klient i jaka jest najczęstsza przyczyna.
4
Porównaj powiązane kody
Użyj odnośników "zobacz też" między mylonymi parami (401 vs 403, 301 vs 302), aby wybrać właściwy kod dla swojego API.
Sukces, ale bez treści. Częsty po wywołaniach DELETE lub PUT, które nie muszą zwracać danych.
Wszystkie trzy to kody sukcesu; różnią się tym, co niesie odpowiedź. 201 powinien zawierać nagłówek Location wskazujący nowy zasób, a 204 z definicji jest pusty.
Tymczasowe przekierowanie. Przeglądarki sprawdzają oryginalny URL przy każdym żądaniu; zakładki zostają na starym adresie.
Używaj 301, gdy zasób naprawdę został przeniesiony (zmiana marki, nowa struktura URL). Używaj 302 do krótkotrwałych przekierowań, np. testów A/B, przekierowań po logowaniu czy stron serwisowych.
Serwer wie, kim jesteś, ale nie masz uprawnień do tego zasobu.
Jeśli inne dane logowania mogłyby pomóc, zwróć 401. Jeśli żadne dane logowania nie pomogą (zasób jest po prostu niedostępny dla tego użytkownika), zwróć 403.
Gateway timeout: pośrednik połączył się z serwerem docelowym, ale nie dostał odpowiedzi na czas.
Wszystkie cztery to błędy serwera, ale przy debugowaniu mówią zupełnie różne rzeczy. 500 to twoja aplikacja, 502 i 504 wskazują na ścieżkę sieciową, a 503 na brak przepustowości.
Częste błędy przy kodach HTTP
Zwracanie 200 OK z {"error": "..."} w treści. Kody statusu są częścią kontraktu: użyj właściwego (400, 404, 500), aby klienci mogli na jego podstawie działać.
Używanie 401 do błędów uprawnień. 401 dotyczy uwierzytelnienia; odmowa uprawnień to 403.
Używanie 200 dla nowo utworzonych zasobów zamiast 201 z nagłówkiem Location.
Zwracanie 404 przy nieautoryzowanym dostępie. Ukrywa to zasób przed sondowaniem, ale myli też klientów z prawidłowym dostępem. 403 jest zwykle jaśniejszy.
Mylenie 429 Too Many Requests z 503 Service Unavailable. Używaj 429 dla limitów żądań na klienta, a 503 dla ogólnego przeciążenia.
Kody HTTP: najczęstsze pytania
Co oznacza błąd HTTP 404?
404 Not Found oznacza, że serwer zrozumiał żądanie, ale zasób pod tym adresem URL nie istnieje. Najczęściej ścieżka jest błędna, zasób został usunięty albo w adresie jest literówka.
Czym różni się kod 401 od 403?
401 Unauthorized oznacza, że nie jesteś uwierzytelniony: serwer nie wie, kim jesteś. 403 Forbidden oznacza, że jesteś uwierzytelniony, ale nie masz uprawnień do zasobu. Inne dane logowania mogą naprawić 401, ale nie naprawią 403.
Czym różni się przekierowanie 301 od 302?
301 Moved Permanently to stałe przekierowanie: przeglądarki i wyszukiwarki aktualizują swoje dane. 302 Found to tymczasowe przekierowanie: klienci dalej odwiedzają oryginalny URL. Używaj 301 przy stałych przeniesieniach, a 302 przy tymczasowych objazdach.
Co oznacza błąd HTTP 500?
500 Internal Server Error to ogólny błąd po stronie serwera, zwykle zgłaszany, gdy nieobsłużony wyjątek wypłynie na wierzch. Klient nie zrobił nic złego: to twój serwer nie przetworzył poprawnego żądania.
Czy zawsze warto używać konkretnego kodu statusu?
Tak. Ogólne 200 OK przy błędach czy 500 na wszystko, co poszło nie tak, utrudnia korzystanie z API. Wybierz najbardziej konkretny pasujący kod: klienci, serwery proxy, systemy monitoringu i logika ponawiania prób działają na podstawie kodu statusu.
Co oznacza kod HTTP 429?
429 Too Many Requests jest wysyłany, gdy klient osiągnął limit żądań. Odpowiedź powinna zawierać nagłówek Retry-After, który mówi klientowi, kiedy może bezpiecznie spróbować ponownie.
Co oznacza błąd HTTP 403 Forbidden?
403 Forbidden oznacza, że serwer zrozumiał żądanie i wie, kim jesteś, ale odmawia dostępu do zasobu. W przeciwieństwie do 401 ponowne uwierzytelnienie nie pomoże: twoje konto po prostu nie ma uprawnień. Typowe przyczyny to brak ról lub zakresów, listy dozwolonych adresów IP albo zasób prywatny innego użytkownika.
Co oznacza błąd HTTP 502 Bad Gateway?
502 Bad Gateway oznacza, że serwer działający jako proxy lub brama (CDN, load balancer lub reverse proxy) otrzymał nieprawidłową lub pustą odpowiedź od serwera docelowego, do którego przekazał twoje żądanie. Zwykle wskazuje to, że backend nie działa, ulega awarii lub jest źle skonfigurowany, a nie że problem leży w twoim żądaniu.
Ile jest kodów HTTP?
Istnieje pięć klas (1xx-5xx) i około 60 standardowych kodów zarejestrowanych w IANA, choć większość jest rzadko używana. W praktyce codzienna praca nad stronami i API opiera się na około 15-20 podstawowych kodach: 200, 201, 204, 301, 302, 304, 400, 401, 403, 404, 409, 422, 429, 500, 502 i 503. Lista z wyszukiwarką powyżej zawiera każdy standardowy kod z prostym opisem.
