405 Method Not Allowed: przyczyny i naprawa

Co oznacza 405 Method Not Allowed

RFC 9110 wymaga, żeby odpowiedź 405 zawierała nagłówek Allow wymieniający metody, które zasób faktycznie obsługuje. Ten nagłówek to cała diagnoza w jednej linii: jeśli żądanie do /api/users zwraca 405 z Allow: GET, HEAD, trasa istnieje i działa dobrze dla odczytu, po prostu nigdy nie miała podpiętego handlera dla metody, którą wysłałeś.

HTTP/1.1 405 Method Not Allowed
Allow: GET, HEAD

Jak pojawia się błąd

Przeglądarki pokazują ogólną stronę błędu dla 405 zwróconego przy zwykłej nawigacji, bo nie jest to przypadek, dla którego mają specjalną obsługę. Dużo częściej trafia się na 405 w zakładce sieciowej, nieudanym wywołaniu AJAX albo awarii preflightu CORS w konsoli, bo większość 405 pochodzi ze skryptowanych żądań, nie z klikniętych linków. Z linii poleceń metoda i nagłówek Allow opowiadają całą historię:

curl -i -X POST https://example.com/downloads/report.pdf
HTTP/1.1 405 Method Not Allowed
Allow: GET, HEAD

Co powoduje 405 Method Not Allowed

• POST do statycznego pliku. Żądanie do faktycznego pliku na dysku, takiego jak PDF albo obraz, serwowanego przez serwer WWW, który odpowiada tylko na GET i HEAD dla treści statycznej.
• Wywołanie trasy definiującej tylko niektóre metody. Trasa frameworka zarejestrowana wyłącznie dla GET z założenia zwraca 405 dla każdego innego czasownika, a nie 404.
• Odrzucone żądanie preflightowe OPTIONS CORS. Przeglądarki wysyłają automatyczne żądanie OPTIONS przed pewnymi wywołaniami cross-origin, a serwer albo gateway bez handlera OPTIONS na tej ścieżce odpowiada 405, co potem ujawnia się w przeglądarce jako zablokowane żądanie cross-origin, a nie czyste 405.
• nginx serwujący blok location przeznaczony do plików statycznych. Blok location używający try_files wobec systemu plików bez proxy_pass odpowie 405 przy POST, bo serwowanie plików statycznych w nginx domyślnie implementuje tylko GET, HEAD i ograniczony zestaw metod.
• Ograniczenia czasowników WebDAV i IIS. IIS i niektóre serwery z WebDAV jawnie dopuszczają czasowniki per ścieżka, a metoda spoza tej listy, w tym niestandardowe jak PROPFIND, dostaje 405, nawet jeśli ogólna trasa poza tym działa.
• Błędna konfiguracja trasy frameworka. Trasa zamierzona pod GET i POST, ale zarejestrowana tylko dla jednej, często po refaktorze, który rozdzielił handler bez aktualizacji deklaracji trasy.
• Lista dopuszczonych metod load balancera albo bramy API. Niektóre bramy ograniczają dozwolone metody per trasa niezależnie od aplikacji, a aplikacja nigdy nawet nie widzi odrzuconego żądania.

Jak rozpoznać, kto zawinił

405 to niemal zawsze problem konfiguracji albo kodu po stronie serwera, a nie coś spowodowane przez odwiedzającego, bo przeglądarki i zwykłe linki nie wysyłają dowolnych metod same z siebie. Jeśli strona w większości działa, ale jedna akcja, taka jak wysłanie formularza albo wywołanie API z JavaScriptu po stronie klienta, zawodzi z 405, sprawdź, czy metoda tego konkretnego żądania zgadza się z tym, czego oczekuje endpoint. Jeśli tak, a błąd jest nowy, najszybszym sposobem potwierdzenia, że zepsuła się konfiguracja trasy albo proxy, jest uruchomienie kontroli HTTP, która wysyła dokładnie tę metodę, której używa Twoja aplikacja, i porównanie wyniku z sytuacją sprzed niedawnego wdrożenia.

Jak naprawić 405 Method Not Allowed

Jeśli jesteś odwiedzającym

1. Przeładuj i powtórz akcję, bo 405 z wysłania formularza może czasem wynikać ze strony, która wczytała nieaktualną, zbuforowaną wersję formularza wskazującą na zły endpoint.
2. Wyczyść cache przeglądarki dla witryny, jeśli problem się utrzymuje, na wypadek, gdyby nieaktualny service worker albo zbuforowana odpowiedź odtwarzały stare, teraz niekompatybilne żądanie.
3. Zgłoś to do witryny, bo to niemal zawsze problem konfiguracji po ich stronie; nie ma naprawy po stronie klienta dla serwera, który naprawdę nie akceptuje danej metody.

Jeśli prowadzisz witrynę

1. Przeczytaj nagłówek Allow we własnej odpowiedzi 405, żeby potwierdzić dokładnie, które metody serwer uważa za poprawne dla tej ścieżki, a potem porównaj z tym, co faktycznie wysyła klient.
2. Dodaj brakującą metodę do trasy. W większości frameworków to jednolinijkowa deklaracja trasy; naprawa rzadko leży w logice aplikacji, gdy już wiesz, którego czasownika brakuje.
3. Obsłuż OPTIONS jawnie dla tras z włączonym CORS. Albo pozwól middleware'owi CORS Twojego frameworka automatycznie odpowiadać na żądania preflightowe, albo dodaj handler zwracający poprawne nagłówki Allow i Access-Control-Allow-Methods.
4. Napraw blok location nginx, jeśli blok statyczny przechwytuje trasę, która potrzebuje backendu. Minimalny przykład, który przepuszcza POST przez proxy zamiast serwować go jako plik:

   location /api/ {
       proxy_pass http://backend;
   }

5. Sprawdź listy dopuszczonych metod gateway'a i load balancera osobno od aplikacji, bo żądanie może zostać odrzucone, zanim w ogóle dotrze do Twojego kodu, a logi aplikacji nic dla niego nie pokażą.

Jak zapobiec cichemu 405 po wdrożeniu

Trasa, która traci metodę podczas refaktoru, albo reguła proxy, która zaczyna przechwytywać ścieżkę, której wcześniej nie dotykała, nie rzuci nigdzie wyjątku, po prostu odpowie złą, ale poprawną odpowiedzią HTTP. Zaplanowana kontrola HTTP z asercją na kodzie statusu, wysyłana dokładnie tą metodą, na której polega Twoja integracja, wyłapuje tę regresję zaraz po wdrożeniu, które ją spowodowało, zamiast po zgłoszeniach użytkowników o zepsutych formularzach. Dla endpointów API konkretnie, monitorowanie API sprawdzające zarówno metodę, jak i treść odpowiedzi, potwierdza, że trasa nie tylko akceptuje żądanie, ale wciąż zachowuje się poprawnie.

Powiązane błędy

Zobacz 404 Not Found dla ścieżki, która w ogóle nie istnieje, w przeciwieństwie do takiej, która istnieje, ale odrzuca metodę, przegląd 4xx dla pełnej rodziny oraz 401 Unauthorized i 422 Unprocessable Content gdzie indziej w tej partii.

Najczęściej zadawane pytania

Jaka jest różnica między 404 a 405?

404 oznacza, że nic nie istnieje pod tą ścieżką dla żadnej metody. 405 oznacza, że ścieżka istnieje i działa dla co najmniej jednej metody, po prostu nie tej, której użyłeś, a nagłówek Allow potwierdza, które metody są ważne.

Dlaczego żądanie CORS zawodzi z czymś, co wygląda jak 405?

Przeglądarki wysyłają automatyczny preflight OPTIONS przed wieloma żądaniami cross-origin. Jeśli serwer nie ma handlera dla OPTIONS na tej trasie, odpowiada 405, a przeglądarka raportuje to w konsoli jako awarię CORS, zamiast pokazać wprost surowy kod statusu.

Czy 405 to kiedykolwiek poprawna odpowiedź, którą API zwraca celowo?

Tak. Jeśli zasób naprawdę obsługuje tylko odczyt, zwrócenie 405 dla PUT albo DELETE wobec niego to poprawne zachowanie REST i jest bardziej informatywne dla wywołującego niż ogólne 404.

Czy zapora albo WAF mogą spowodować 405?

Zdarza się to rzadziej niż błędna konfiguracja aplikacji albo proxy, ale niektóre zestawy reguł WAF ograniczają dozwolone metody per ścieżka i odpowiedzą 405 albo podobną blokadą, zanim żądanie w ogóle dotrze do serwera źródłowego.

Dlaczego nagłówek Allow czasem wymienia metody, które i tak zawodzą?

Nagłówek Allow odzwierciedla to, dla czego zarejestrowana jest trasa, niekoniecznie to, co jest w pełni zaimplementowane. Metoda może być zadeklarowana i wciąż zwracać błąd z innego powodu, na przykład brakującej autoryzacji, już po przejściu kontroli metody.