błąd 401

Błąd 401 (Unauthorized) to kod odpowiedzi HTTP informujący, że żądanie nie zostało zrealizowane, ponieważ dostęp do zasobu wymaga uwierzytelnienia, a klient nie przekazał ważnych poświadczeń. Wbrew dosłownemu tłumaczeniu nazwy chodzi o brak uwierzytelnienia (authentication), nie autoryzacji — serwer nie wie, kim jest nadawca żądania.

Jak działa błąd 401

Typowy przebieg wygląda tak: klient żąda chronionego zasobu bez poświadczeń, serwer odpowiada kodem 401 wraz z nagłówkiem WWW-Authenticate wskazującym oczekiwany schemat uwierzytelnienia (Basic, Bearer, Digest), a klient ponawia żądanie z nagłówkiem Authorization. W komunikacji z API najczęstsze źródła błędu to wygasły lub uszkodzony token JWT, nieprawidłowy klucz API albo brak nagłówka Authorization w ogóle. W klasycznych serwisach WWW 401 zwraca zwykle ochrona katalogu mechanizmem Basic Auth (pliki .htpasswd) lub wygaśnięcie sesji użytkownika.

Zastosowanie w praktyce

Diagnozę warto zacząć od poświadczeń: czy login i hasło są poprawne, czy token nie wygasł (pole exp w JWT) i czy jest wysyłany we właściwym nagłówku. Kolejne kroki to weryfikacja konfiguracji Basic Auth na serwerze, wyczyszczenie ciasteczek i pamięci podręcznej przeglądarki oraz sprawdzenie, czy adres nie wymaga innego mechanizmu logowania (np. tokenu OAuth zamiast klucza statycznego). Od strony bezpieczeństwa seria odpowiedzi 401 w logach serwera to cenny sygnał — może oznaczać próbę ataku brute force na panel logowania, którą warto ograniczyć narzędziami typu fail2ban lub limitem żądań. Różnicę względem pokrewnego kodu wyjaśnia hasło błąd 403: tam serwer rozpoznaje klienta, lecz świadomie odmawia dostępu. W nowoczesnych API dobrym zwyczajem jest zwracanie wraz z kodem 401 czytelnej treści błędu w formacie JSON, opisującej przyczynę (np. wygasły token) i sposób ponownego uwierzytelnienia, co znacząco upraszcza integrację i diagnostykę po stronie klienta.