405 Method Not Allowed: příčiny a opravy

Co znamená 405 Method Not Allowed

RFC 9110 vyžaduje, aby odpověď 405 obsahovala hlavičku Allow se seznamem metod, které daný prostředek skutečně podporuje. Tahle hlavička je celá diagnóza v jednom řádku: pokud požadavek na /api/users vrátí 405 s Allow: GET, HEAD, trasa existuje a pro čtení funguje v pořádku, jen pro ni nikdy nebyl zapojený handler pro metodu, kterou jste poslali.

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

Jak se chyba projevuje

Prohlížeče zobrazí obecnou chybovou stránku pro 405 vrácenou při běžné navigaci, protože tohle není případ, na který by měly zvláštní zpracování. Mnohem běžnější je narazit na 405 na kartě sítě, u selhaného volání AJAX, nebo u selhání CORS preflight v konzoli, protože většina 405 pochází ze skriptovaných požadavků, ne z proklikaných odkazů. Z příkazové řádky říká metoda a hlavička Allow celý příběh:

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

Co způsobuje 405 Method Not Allowed

• POST na statický soubor. Požadavek na skutečný soubor na disku, jako PDF nebo obrázek, obsluhovaný webovým serverem, který na statický obsah odpovídá jen GET a HEAD.
• Volání trasy, která definuje jen některé metody. Trasa frameworku zaregistrovaná jen pro GET vrací pro každé jiné sloveso 405, záměrně, ne 404.
• Odmítnutý preflight požadavek OPTIONS pro CORS. Prohlížeče před určitými cross-origin voláními posílají automatický požadavek OPTIONS, a server nebo brána, které pro tuto cestu nemají handler pro OPTIONS, odpoví 405, což se v prohlížeči pak projeví jako zablokovaný cross-origin požadavek, ne jako jasná 405.
• nginx obsluhující location blok určený pro statické soubory. Blok location používající try_files proti souborovému systému bez proxy_pass vrátí na POST 405, protože obsluha statických souborů v nginx implementuje jen GET, HEAD, a ve výchozím stavu omezenou sadu metod.
• Omezení sloves WebDAV a IIS. IIS a některé servery s podporou WebDAV výslovně povolují slovesa podle cesty, a metoda mimo tenhle seznam, včetně vlastních jako PROPFIND, dostane 405, i když obecná trasa jinak funguje.
• Špatná konfigurace trasy frameworku. Trasa určená k přijímání GET i POST, ale zaregistrovaná jen pro jedno z nich, často po refaktoringu, který rozdělil handler bez aktualizace deklarace trasy.
• Seznam povolených metod load balanceru nebo brány API. Některé brány omezují povolené metody podle trasy nezávisle na aplikaci, a aplikace odmítnutý požadavek vůbec nikdy neuvidí.

Jak zjistit, čí je to chyba

405 je skoro vždy problém konfigurace nebo kódu na straně serveru, ne něco způsobené návštěvníkem, protože prohlížeče a běžné odkazy samy o sobě neposílají libovolné metody. Pokud stránka většinou funguje, ale jedna akce, jako odeslání formuláře nebo volání API z klientského JavaScriptu, selže s 405, zkontrolujte, jestli metoda daného konkrétního požadavku odpovídá tomu, co endpoint očekává. Pokud ano a chyba je nová, nejrychlejší způsob, jak potvrdit, že se rozbila konfigurace trasy nebo proxy, je spustit HTTP kontrolu, která pošle přesně tu metodu, kterou vaše aplikace používá, a porovnat výsledek napříč nedávným nasazením.

Jak opravit 405 Method Not Allowed

Pokud jste návštěvník

1. Znovu načtěte a zkuste akci znovu, protože 405 z odeslání formuláře může někdy následovat po stránce, která načetla zastaralou cachovanou verzi formuláře mířícího na špatný endpoint.
2. Vymažte cache prohlížeče pro daný web, pokud problém přetrvává, pro případ, že zastaralý service worker nebo cachovaná odpověď přehrává starý, teď už nekompatibilní požadavek.
3. Nahlaste to webu, protože tohle je téměř ve všech případech problém konfigurace na jejich straně; pro server, který danou metodu skutečně nepřijímá, neexistuje žádná oprava na straně klienta.

Pokud web provozujete

1. Přečtěte si hlavičku Allow ve vlastní odpovědi 405, abyste potvrdili přesně, které metody server pro danou cestu považuje za platné, a pak to porovnejte s tím, co klient skutečně posílá.
2. Přidejte chybějící metodu do trasy. Na většině frameworků je to jednořádková deklarace trasy; oprava jen zřídka spočívá v logice aplikace, jakmile víte, které sloveso chybí.
3. Zpracujte OPTIONS výslovně u tras s podporou CORS. Buď nechte middleware CORS vašeho frameworku odpovídat na preflight požadavky automaticky, nebo přidejte handler, který vrátí správné hlavičky Allow a Access-Control-Allow-Methods.
4. Opravte location blok nginx, pokud blok pro statické soubory zachytává trasu, která potřebuje backend. Minimální příklad, který místo obsluhy jako souboru předá POST přes proxy:

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

5. Zkontrolujte seznamy povolených metod brány a load balanceru odděleně od aplikace, protože požadavek může být odmítnutý dřív, než se vůbec dostane k vašemu kódu, a logy aplikace pro něj nic neukážou.

Jak předejít tichému výpadku 405 po nasazení

Trasa, která během refaktoringu ztratí metodu, nebo pravidlo proxy, které začne zachytávat cestu, kterou dřív nezachytávalo, nikde nevyhodí výjimku, prostě jen odpoví špatnou, ale platnou HTTP odpovědí. Naplánovaná HTTP kontrola s ověřením stavového kódu, odeslaná s přesně tou metodou, na kterou se spoléhá vaše integrace, zachytí tuhle regresi hned po nasazení, které ji způsobilo, místo až poté, co uživatelé nahlásí rozbité formuláře. Konkrétně u endpointů API monitoring API, který kontroluje metodu i tělo odpovědi, potvrdí, že trasa požadavek nejen přijímá, ale i pořád funguje správně.

Související chyby

Viz 404 Not Found pro cestu, která vůbec neexistuje, na rozdíl od té, která existuje, ale odmítá metodu, přehled 4xx pro celou rodinu, a 401 Unauthorized a 422 Unprocessable Content jinde v této dávce.

Často kladené otázky

Jaký je rozdíl mezi 404 a 405?

404 znamená, že na dané cestě neexistuje nic pro žádnou metodu. 405 znamená, že cesta existuje a funguje aspoň pro jednu metodu, jen ne tu, kterou jste použili, a hlavička Allow potvrdí, které metody jsou platné.

Proč požadavek CORS selže s něčím, co vypadá jako 405?

Prohlížeče před mnoha cross-origin požadavky posílají automatický preflight OPTIONS. Pokud server pro danou trasu nemá handler pro OPTIONS, odpoví 405, a prohlížeč to v konzoli nahlásí jako selhání CORS, místo aby zobrazil přímo surový stavový kód.

Je 405 někdy správná odpověď, kterou má API poslat záměrně?

Ano. Pokud prostředek skutečně podporuje jen čtení, vrácení 405 na PUT nebo DELETE proti němu je správné chování REST, a je to pro volajícího informativnější, než by byla obecná 404.

Může 405 způsobit firewall nebo WAF?

Je to méně časté než špatná konfigurace aplikace nebo proxy, ale některé sady pravidel WAF omezují povolené metody podle cesty a odpoví 405 nebo podobnou blokací ještě předtím, než se požadavek vůbec dostane k originu.

Proč hlavička Allow občas uvádí metody, které pořád selhávají?

Hlavička Allow odráží to, pro co je trasa zaregistrovaná, ne nutně to, co je plně implementované. Metoda může být deklarovaná a přesto vrátit chybu z jiných důvodů, jako chybějící autorizace, jakmile projde kontrolou metody.