405 Method Not Allowed: причини і виправлення

Що означає 405 Method Not Allowed

RFC 9110 вимагає, щоб відповідь 405 включала заголовок Allow, що перелічує методи, які ресурс справді підтримує. Цей заголовок - уся діагностика в одному рядку: якщо запит до /api/users повертає 405 з Allow: GET, HEAD, маршрут існує й прекрасно працює для читання, у нього просто ніколи не було обробника для того методу, який ви надіслали.

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

Як з'являється помилка

Браузери показують загальну сторінку помилки для 405, повернутого при звичайній навігації, оскільки це не той випадок, для якого в них є спеціальна обробка. Значно частіше 405 трапляється у вкладці мережі, невдалому виклику AJAX чи збої CORS-preflight у консолі, оскільки більшість 405 приходять від скриптованих запитів, а не натиснутих посилань. З командного рядка метод і заголовок Allow розповідають усю історію:

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

Що спричиняє 405 Method Not Allowed

• POST на статичний файл. Запит до справжнього файлу на диску, наприклад PDF чи зображення, що обслуговує вебсервер, який відповідає лише на GET і HEAD для статичного вмісту.
• Виклик маршруту, що визначає лише деякі методи. Маршрут фреймворку, зареєстрований лише для GET, повертає 405 для кожного іншого дієслова навмисно, а не 404.
• Відхилений CORS-preflight запит OPTIONS. Браузери надсилають автоматичний запит OPTIONS перед певними міждоменними викликами, і сервер чи шлюз без обробника для OPTIONS на цьому шляху відповідає 405, що потім проявляється в браузері як заблокований міждоменний запит, а не чіткий 405.
• nginx обслуговує блок location, призначений для статичних файлів. Блок location, що використовує try_files проти файлової системи без proxy_pass, дасть 405 на POST, оскільки обслуговування статичних файлів у nginx реалізує лише GET, HEAD і за замовчуванням обмежений набір методів.
• Обмеження дієслів WebDAV і IIS. IIS і деякі сервери з увімкненим WebDAV явно ведуть білий список дієслів для кожного шляху, і метод поза цим списком, включно з власними на кшталт PROPFIND, отримує 405, навіть якщо загальний маршрут інакше працює.
• Неправильна конфігурація маршруту фреймворку. Маршрут, задуманий приймати і GET, і POST, але зареєстрований лише для одного, часто після рефакторингу, що розділив обробник без оновлення декларації маршруту.
• Білий список методів балансувальника навантаження чи API-шлюзу. Деякі шлюзи обмежують дозволені методи для кожного маршруту незалежно від застосунку, і застосунок навіть не бачить відхилений запит.

Як зрозуміти, хто винен

405 майже завжди - проблема конфігурації чи коду на боці сервера, а не щось, спричинене відвідувачем, оскільки браузери й звичайні посилання самі не надсилають довільних методів. Якщо сторінка здебільшого працює, а одна дія, на кшталт відправлення форми чи виклику API з клієнтського JavaScript, провалюється з 405, перевірте, чи метод саме цього запиту збігається з тим, що очікує ендпоінт. Якщо так, а помилка нова, найшвидший спосіб підтвердити, що зламалася конфігурація маршруту чи проксі, - запустити HTTP-перевірку, що надсилає точно той метод, який використовує ваш застосунок, і порівняти результат до і після недавнього деплою.

Як виправити 405 Method Not Allowed

Якщо ви відвідувач

1. Перезавантажте і повторіть дію, оскільки 405 від відправлення форми іноді може йти за сторінкою, що завантажила застарілу закешовану версію форми, спрямовану не на той ендпоінт.
2. Очистіть кеш браузера для сайту, якщо проблема триває, на випадок, коли застарілий service worker чи закешована відповідь відтворює старий, уже несумісний запит.
3. Повідомте про це сайту, оскільки майже завжди це проблема конфігурації на їхньому боці; для сервера, що справді не приймає метод, немає виправлення з боку клієнта.

Якщо ви керуєте сайтом

1. Прочитайте заголовок Allow у власній відповіді 405, щоб точно підтвердити, які методи сервер вважає валідними для цього шляху, а тоді порівняйте це з тим, що фактично надсилає клієнт.
2. Додайте відсутній метод до маршруту. У більшості фреймворків це декларація маршруту в один рядок; виправлення рідко в логіці застосунку, щойно ви знаєте, якого дієслова бракує.
3. Явно обробляйте OPTIONS для маршрутів з увімкненим CORS. Або дозвольте проміжному ПЗ CORS вашого фреймворку автоматично відповідати на preflight-запити, або додайте обробник, що повертає правильні заголовки Allow і Access-Control-Allow-Methods.
4. Виправте блок location у nginx, якщо блок для статичних файлів перехоплює маршрут, якому потрібен бекенд. Мінімальний приклад, що проксіює POST далі замість обслуговування як файл:

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

5. Перевіряйте білі списки методів шлюзу й балансувальника навантаження окремо від застосунку, оскільки запит може відхилити ще до того, як він узагалі дістанеться вашого коду, і логи застосунку нічого про це не покажуть.

Як запобігти мовчазному 405 після деплою

Маршрут, що втрачає метод під час рефакторингу, чи правило проксі, що починає перехоплювати шлях, якого раніше не чіпало, ніде не викине виняток, воно просто дасть неправильну, але валідну HTTP-відповідь. Запланована HTTP-перевірка з умовою на код статусу, надіслана з точним методом, на який покладається ваша інтеграція, ловить цю регресію одразу після деплою, що її спричинив, а не після того, як користувачі повідомлять про зламані форми. Для API-ендпоінтів зокрема API-моніторинг, що перевіряє і метод, і тіло відповіді, підтверджує, що маршрут не лише приймає запит, а й досі поводиться правильно.

Пов'язані помилки

Дивіться 404 Not Found для шляху, що взагалі не існує, на відміну від того, що існує, але відхиляє метод, огляд 4xx для повної родини, і 401 Unauthorized та 422 Unprocessable Content деінде в цій партії.

Часті запитання

Яка різниця між 404 і 405?

404 означає, що за цим шляхом взагалі нічого не існує для жодного методу. 405 означає, що шлях існує і працює принаймні для одного методу, просто не того, що ви використали, а заголовок Allow підтверджує, які методи валідні.

Чому CORS-запит провалюється тим, що виглядає як 405?

Браузери надсилають автоматичний OPTIONS-preflight перед багатьма міждоменними запитами. Якщо в сервера немає обробника для OPTIONS на цьому маршруті, він відповідає 405, і браузер повідомляє про це в консолі як збій CORS, а не показує сирий код статусу напряму.

Чи буває 405 коли-небудь правильною відповіддю, яку API навмисно надсилає?

Так. Якщо ресурс справді підтримує лише читання, повернення 405 для PUT чи DELETE проти нього - правильна REST-поведінка, і це інформативніше для викликача, ніж був би загальний 404.

Чи може брандмауер чи WAF спричинити 405?

Це менш поширено, ніж неправильна конфігурація застосунку чи проксі, але деякі набори правил WAF обмежують дозволені методи для кожного шляху й відповідають 405 чи схожим блоком ще до того, як запит узагалі дістанеться origin-сервера.

Чому заголовок Allow іноді перелічує методи, що все одно провалюються?

Заголовок Allow відображає те, для чого зареєстрований маршрут, не обов'язково те, що повністю реалізовано. Метод може бути оголошений і все одно повертати помилку з інших причин, наприклад через відсутню авторизацію, щойно він проходить перевірку методу.