W świecie sieciowych aplikacji i usług internetowych Error 406 jest jednym z mniej przeglądanych, ale istotnych kodów stanu HTTP. Choć nie jest tak powszechny jak 404 czy 500, potrafi wywołać frustrację zarówno po stronie użytkownika, jak i programisty. W niniejszym artykule wyjaśniamy, czym dokładnie jest Error 406, dlaczego się pojawia, jakie są typowe przyczyny, a także jak skutecznie diagnozować i naprawiać ten błąd. Dodatkowo podajemy praktyczne wskazówki dotyczące konfiguracji serwera, diagnostyki żądań i dobrych praktyk SEO, które pomagają zminimalizować negatywny wpływ na działanie witryny.
Co to jest Error 406 i dlaczego się pojawia?
HTTP 406 Not Acceptable to odpowiedź serwera, która sygnalizuje, że żądanie klienta zawiera żądanie co do treści lub formatu (np. typu MIME) w sposób, którego serwer nie jest w stanie spełnić. W praktyce chodzi o negocjację treści: klient prosi o reprezentację zasobu w konkretnym formacie, a serwer nie ma możliwości dostarczenia takiej reprezentacji, która odpowiada warunkom Accept, Accept-Language i podobnym nagłówkom.
Wbrew częstemu myśleniu 406 nie jest przypadkiem całkowitego braku zasobu. Zwykle zasób istnieje, ale nie ma przedstawienia, które spełnia żądane kryteria. Różni się od bardziej znanych kodów jak 404 (nie znaleziono) czy 500 (wewnętrzny błąd serwera) tym, że problem dotyczy sposób prezentacji treści, a nie samego zasobu.
Rola negocjacji treści w protokole HTTP
Podstawą Error 406 jest mechanizm negocjacji treści. Serwer i klient negocjują, w jakim formacie ma być dostarczona treść. Klient może wysłać nagłówki:
- Accept: typy_mime, uprawnienia, preferencje (np. application/json, text/html)
- Accept-Language: język preferowany (np. pl-PL, en-US)
- Accept-Encoding: kompresje (np. gzip)
Jeśli żądanie nie może być spełnione zgodnie z tym zestawem kryteriów, serwer może zwrócić Error 406. W praktyce oznacza to, że nie ma sensownego sposobu przedstawienia treści zgodnie z warunkami klienta, albo konfiguracja serwera nie dopuszcza wystąpienia żądanej reprezentacji.
Typowe przyczyny występowania Error 406
Brak akceptowalnych formatów odpowiadających żądaniu
Główna przyczyna 406 to brak dostępnych reprezentacji zasobu, które spełniają żądane typy MIME. Na przykład, api zwraca dane wyłącznie w JSON, a przeglądarka żąda także formatu XML lub HTML, a serwer nie ma takiego wariantu.
Niewłaściwa konfiguracja serwera do negocjacji treści
Niektóre serwery domyślnie włączają zaawansowaną negocjację treści (np. Apache z modułem mod_negotiation). Jeśli konfiguracja nie jest przemyślana, mogą wystąpić błędy 406 nawet jeśli zasób ma alternatywne reprezentacje.
Problemy z nagłówkami Accept-Language i związanymi reprezentacjami
Jeśli zasób ma wersje językowe i serwer nie widzi dopasowania języka, może zwrócić 406 jako rezultat braku zgodnych wersji treści.
Pośrednicy i proxy
Proxy, load balancers lub CDN-y mogą ingerować w nagłówki żądania lub w politykę negocjacji treści, co skutkuje generowaniem Error 406 nawet gdy backend teoretycznie ma kompatybilne odpowiedzi.
Konfiguracja a pliki kontekstowe
Niekiedy problem leży w tym, że plik konfiguracyjny (np. .htaccess w Apache lub plik konfiguracyjny Nginx) wymusza konkretne formaty i wyklucza inne, prowadząc do Not Acceptable.
Symptomy i objawy błędu 406
Świadome rozpoznanie 406 zależy od kontekstu:
- Przeglądarka wyświetla stronę błędu 406 lub przekierowuje do innego zasobu.
- API zwraca kod odpowiedzi 406 wraz z komunikatem w ciele (JSON lub XML).
- Logi serwera (Apache/Nginx/IIS) zawierają wpis 406 Not Acceptable z odpowiednimi nagłówkami.
- W narzędziach deweloperskich przeglądarki widoczne są różnice w nagłówkach Accept i odpowiadających formatów.
W praktyce, kiedy widzisz Error 406, zwykle warto przeanalizować, czy żądanie nie wymusza niestandardowego formatu, a serwer nie obsługuje takiego formatu w kontekście żądania zasobu.
Diagnostyka krok po kroku: jak rozpoznać źródło Error 406
Sprawdzenie nagłówków żądania
Najpierw sprawdź nagłówki Accept, Accept-Language, Accept-Encoding. Czy zasób ma dostępne reprezentacje dla zadanych typów MIME i wersji językowych? Jeśli nie, to może być przyczyna Error 406.
Testy za pomocą curl
Najprostszy sposób na reprodukcję problemu to narzędzie curl. Poniżej przykładowe komendy:
curl -i -H "Accept: application/json" https://example.com/api/resourcecurl -i -H "Accept: text/html,application/xhtml+xml" https://example.com/pageJeśli serwer zwraca 406, spróbuj poszerzyć lub zmienić Accept, np. dodając również text/html lub aplikacje xml, aby zobaczyć, czy serwer zwróci alternatywną reprezentację.
Analiza logów serwera
Patrzenie w logi serwera (access.log, error.log) pomoże zidentyfikować, jakie żądanie było wysłane i jakie nagłówki były obecne. Szukaj wpisów 406 Not Acceptable i powiązanych zapytań.
Weryfikacja konfiguracji serwera
Sprawdź, czy w konfiguracji serwera nie ma ustawień, które ograniczają dopuszczalne typy MIME lub włącza niepożądaną negocjację treści (np. MultiViews w Apache, które mogą powodować automatyczną negocjację).
Naprawa po stronie klienta: co może zrobić użytkownik lub deweloper API
Uproszczenie żądania i dopasowanie Accept
Najczęściej wystarczy dopasować Accept do reprezentacji, którą serwer faktycznie może zwrócić. Na przykład, jeśli API zwraca JSON, użyj Accept: application/json. Jeśli przeglądarka żąda HTML, upewnij się, że serwer ma HTML jako jedną z reprezentacji.
Podanie alternatywnego formatu
W przypadku, gdy serwer nie może zwrócić preferowanego formatu, rozważ podanie zakresu akceptowanych formatów lub zostawienie bez preferencji (Accept: */*), aby serwer mógł wybrać domyślny format.
Testy regresyjne i fallback
Wdrażając klienta API, warto dodać fallbackowy przypadek, w którym w przypadku braku dopasowania formatu klient sam wybiera domyślny typ (np. JSON dla API) i obsługuje go niezależnie od preferencji użytkownika.
Uwzględnienie języka i lokalizacji
Jeżeli Not Acceptable dotyczy języka, dopilnuj, by Accept-Language obejmował żądane lokalizacje, a zasób miał kopie w potrzebnych wersjach językowych.
Naprawa po stronie serwera: konfiguracja, która ma znaczenie
Nginx
W Nginx problem 406 może wynikać z błędnej konfiguracji negocjacji treści lub z wykluczenia pewnych formatów. Poniżej przykładowe podejście, które może zminimalizować ryzyko 406:
location / {
# wyłączenie zaawansowanej negocjacji, jeśli nie jest potrzebna
try_files $uri $uri/ =404;
add_header Vary Accept;
}
W niektórych przypadkach warto rozważyć wyłączenie MultiViews, jeśli był włączony przez inne ustawienia:
# wyłącza negocjację treści w kontekście serwera
try_files $uri =404;
Apache
W Apache Not Acceptable może być wynikiem mod_negotiation i multi-views. Typowe porady:
- Wyłącz MultiViews, aby ograniczyć automatyczną negocjację treści: Options -MultiViews
- Popraw pliki konfiguracyjne, aby zapewnić, że zasoby mają przynajmniej jedną akceptowalną reprezentację (np. pliki HTML, JSON, XML)
- Upewnij się, że aplikacja generuje odpowiedni typ MIME i nagłówki
Przykładowa konfiguracja:
Options -MultiViews
AddType application/json .json
IIS
W środowiskach Windows IIS również mogą prowadzić do Not Acceptable w przypadku złożonych negocjacji treści. Warto sprawdzić, czy reguły MIME i rozszerzeń obsługują konieczne formaty.
Przykładowe scenariusze biznesowe i praktyczne przypadki
E-commerce: strona produktu i różne formaty danych
Wyobraź sobie sklep online, który udostępnia dane produktu w HTML dla przeglądarki, JSON dla API i XML dla integratorów. Jeśli żądanie wysłane przez frontend nie zawiera dopasowanego Accept, serwer może zwrócić Error 406. Rozwiązaniem jest zapewnienie co najmniej jednego domyślnego formatu lub wprowadzenie kaskadowego podejścia: HTML dla przeglądarki, JSON dla API. Dodatkowo warto dodać nagłówek Vary: Accept, aby poprawić caching i SEO.
APIs i mikroserwisy: spójność negocjacji treści
W architekturze API microservices różne serwisy mogą zwracać różne formaty. Należy ustalić, że wszystkie publiczne endpointy zwracają JSON jako domyślny format, a inne formaty są dostępne na żądanie. Dzięki temu Error 406 nie pojawi się nagle w jednym z serwisów, a klient wie, jakie żądania prowadzić.
Strony statyczne vs. dynamiczna generacja treści
Statyczne strony HTML rzadziej generują Error 406, ale dynamiczna generacja treści lub szablonów może prowadzić do 406, jeśli żądane formaty nie są obsługiwane w danym kontekście. W takich przypadkach warto zadbać o fallback do HTML lub o obsługę nagłówków Accept.
Najlepsze praktyki i checklisty
- Dokumentuj, które formaty treści są obsługiwane dla każdego zasobu i z jakich języków wynika Not Acceptable.
- W przypadku API oparcie na JSON jako domyślnym formacie minimalizuje ryzyko 406.
- Używaj nagłówków Vary: Accept i Vary: Accept-Language w odpowiedziach serwera, aby poprawić caching i spójność danych.
- W konfiguracji serwera wyłączaj niepotrzebną negocjację treści (np. MultiViews), jeśli nie jest wymagana.
- Loguj szczegółowe informacje o żądaniach prowadzących do 406 — nagłówki, ścieżki i czas.
- Testuj scenariusze edge cases: Accept: application/json, Accept: text/html, Accept: */* itd.
Jak testować i weryfikować poprawki
Testy ręczne i automatyczne
Podstawą testów jest wysyłanie żądań z różnymi Accept header i obserwowanie, czy serwer zwraca odpowiednią reprezentację zamiast 406. Automatyczne testy API (np. Postman, Insomnia, testy w frameworkach CI) powinny obejmować przypadki pozytywne i negatywne dla negocjacji treści.
Przykładowe scenariusze testowe
- Żądanie HTML bez Accept: text/html — czy serwer zwraca HTML lub 200 OK?
- Żądanie JSON, ale zasób nie ma JSON – czy 406 jest właściwie zwracane?
- Żądanie z Accept: application/json, Accept-Language: en-US — czy serwer zwraca JSON w odpowiednim języku?
Podsumowanie: jak uniknąć Error 406 w przyszłości
Error 406 to sygnał konieczności dopasowania negocjacji treści. Dobre praktyki obejmują jasną komunikację formatu danych, spójne domyślne reprezentacje, unikanie złożonych konfiguracji negocjacji przy użyciu narzędzi takich jak MultiViews, a także weryfikację parametrów Accept i Accept-Language na etapie projektowania API i strony internetowej. Dzięki temu zarówno użytkownicy, jak i systemy integracyjne otrzymują przewidywalne i stabilne odpowiedzi, a ryzyko wystąpienia błędu Error 406 zostaje ograniczone do minimum.
Najczęściej zadawane pytania
- Czy Error 406 oznacza, że zasób nie istnieje? Nie — to problem z prezentacją treści, nie z samym zasobem.
- Czy mogę wyłączyć negocjację treści? Tak, na poziomie konfiguracji serwera, o ile nie jest to niezbędne dla funkcjonalności twojej aplikacji.
- Czy 406 wpływa na SEO? Notatka: 406 może wpływać na crawlowanie, jeśli występuje w sposób nieregularny. Utrzymuj spójne odpowiedzi i zastosuj nagłówki Vary.
Podsumowując, Error 406 to problem, który łatwo wyjaśnić i łatwo naprawić, jeśli podejdzie się do niego z odpowiednią strategią negocjacji treści oraz przemyślaną konfiguracją serwera. Dzięki temu użytkownicy będą mieli przejrzyste i przewidywalne doświadczenie przeglądania, a zespoły deweloperskie będą w stanie szybciej diagnozować i usuwać źródła błędów.