405 Method Not Allowed: cause e soluzioni

Cosa significa 405 Method Not Allowed

RFC 9110 richiede che una risposta 405 includa un header Allow che elenca i metodi che la risorsa effettivamente supporta. Quell'header è l'intera diagnosi in una riga: se una richiesta a /api/users restituisce 405 con Allow: GET, HEAD, la rotta esiste e funziona bene per la lettura, semplicemente non ha mai avuto un handler collegato per qualunque metodo tu abbia inviato.

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

Come appare l'errore

I browser mostrano una pagina di errore generica per un 405 restituito a una normale navigazione, dato che questo non è un caso per cui hanno una gestione speciale. È molto più comune incontrare un 405 in una scheda di rete, una chiamata AJAX fallita, o un fallimento di preflight CORS nella console, perché la maggior parte dei 405 proviene da richieste scriptate piuttosto che da link cliccati. Dalla riga di comando, il metodo e l'header Allow raccontano l'intera storia:

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

Cosa causa un 405 Method Not Allowed

• Inviare una POST verso un file statico. Una richiesta per un file reale su disco, come un PDF o un'immagine, servito da un web server che risponde solo a GET e HEAD per il contenuto statico.
• Chiamare una rotta che definisce solo alcuni metodi. Una rotta di framework registrata solo per GET restituisce 405 per ogni altro verbo, per progettazione, invece di 404.
• Una richiesta preflight OPTIONS CORS rifiutata. I browser inviano automaticamente una richiesta OPTIONS prima di certe chiamate cross-origin, e un server o gateway che non ha alcun handler per OPTIONS su quel percorso risponde 405, il che poi si manifesta nel browser come una richiesta cross-origin bloccata piuttosto che un chiaro 405.
• nginx che serve un blocco location pensato per file statici. Un blocco location che usa try_files contro il filesystem senza proxy_pass restituirà 405 su POST, dato che servire file statici in nginx implementa solo GET, HEAD, e per impostazione predefinita un insieme limitato di metodi.
• Restrizioni sui verbi di WebDAV e IIS. IIS e alcuni server abilitati per WebDAV mettono esplicitamente in allowlist i verbi per percorso, e un metodo fuori da quella lista, inclusi quelli personalizzati come PROPFIND, riceve 405 anche se la rotta generale funziona altrimenti.
• Configurazione errata delle rotte del framework. Una rotta pensata per accettare sia GET sia POST ma registrata solo per uno dei due, spesso dopo un refactoring che ha diviso un handler senza aggiornare la dichiarazione della rotta.
• Un'allowlist di metodi di un load balancer o gateway API. Alcuni gateway restringono i metodi permessi per rotta indipendentemente dall'applicazione, e l'app non vede mai nemmeno la richiesta rifiutata.

Come capire di chi è la colpa

Un 405 è quasi sempre un problema di configurazione o codice lato server piuttosto che qualcosa causato da un visitatore, dato che i browser e i link normali non inviano metodi arbitrari da soli. Se una pagina funziona per lo più ma un'azione, come l'invio di un modulo o una chiamata API dal JavaScript lato client, fallisce con 405, controlla se il metodo di quella specifica richiesta corrisponde a ciò che l'endpoint si aspetta. Se corrisponde e l'errore è nuovo, il modo più veloce per confermare che una configurazione di rotta o proxy si sia rotta è eseguire un controllo HTTP che invia l'esatto metodo che la tua applicazione usa e confrontare il risultato attraverso un deploy recente.

Come correggere un 405 Method Not Allowed

Se sei un visitatore

1. Ricarica e riprova l'azione, dato che un 405 da un invio di modulo può a volte seguire una pagina che ha caricato una versione obsoleta in cache del modulo puntata verso l'endpoint sbagliato.
2. Cancella la cache del browser per il sito se il problema persiste, nel caso un service worker obsoleto o una risposta in cache stia ripetendo una vecchia richiesta ormai incompatibile.
3. Segnalalo al sito, dato che questo è un problema di configurazione dal loro lato in quasi ogni caso; non c'è alcuna correzione lato client per un server che davvero non accetta il metodo.

Se gestisci il sito

1. Leggi l'header Allow sulla tua stessa risposta 405 per confermare esattamente quali metodi il server ritiene validi per quel percorso, poi confrontalo con ciò che il client sta effettivamente inviando.
2. Aggiungi il metodo mancante alla rotta. Sulla maggior parte dei framework questa è una dichiarazione di rotta di una riga; la correzione raramente sta nella logica applicativa una volta che sai quale verbo manca.
3. Gestisci esplicitamente OPTIONS per le rotte abilitate a CORS. O lascia che il middleware CORS del tuo framework risponda automaticamente alle richieste preflight, oppure aggiungi un handler che restituisce gli header Allow e Access-Control-Allow-Methods corretti.
4. Correggi il blocco location di nginx se un blocco per file statici sta intercettando una rotta che ha bisogno di un backend. Un esempio minimo che inoltra POST tramite proxy invece di servirla come file:

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

5. Controlla le allowlist di metodi del gateway e del load balancer separatamente dall'applicazione, dato che una richiesta può essere rifiutata prima di raggiungere mai il tuo codice, e i log applicativi non mostreranno nulla per essa.

Come prevenire un 405 silenzioso dopo un deploy

Una rotta che perde un metodo durante un refactoring, o una regola proxy che inizia a intercettare un percorso che prima non intercettava, non lancerà un'eccezione da nessuna parte, risponderà semplicemente con una risposta HTTP sbagliata ma valida. Un controllo HTTP pianificato con un'asserzione sul codice di stato, inviato con l'esatto metodo su cui la tua integrazione fa affidamento, coglie quella regressione subito dopo il deploy che l'ha causata invece che dopo che gli utenti segnalano moduli rotti. Per gli endpoint API in particolare, il monitoraggio API che controlla sia il metodo sia il corpo della risposta conferma che la rotta non solo accetta la richiesta ma si comporta ancora correttamente.

Errori correlati

Vedi 404 Not Found per un percorso che non esiste affatto, in contrapposizione a uno che esiste ma rifiuta il metodo, la panoramica 4xx per l'intera famiglia, e 401 Unauthorized e 422 Unprocessable Content altrove in questo lotto.

Domande frequenti

Qual è la differenza tra 404 e 405?

404 significa che non esiste nulla a quel percorso per alcun metodo. 405 significa che il percorso esiste e funziona per almeno un metodo, semplicemente non quello che hai usato, e l'header Allow conferma quali metodi sono validi.

Perché una richiesta CORS fallisce con qualcosa che sembra un 405?

I browser inviano automaticamente un preflight OPTIONS prima di molte richieste cross-origin. Se il server non ha alcun handler per OPTIONS su quella rotta, risponde 405, e il browser lo riporta come un fallimento CORS nella console invece di mostrare direttamente il codice di stato grezzo.

Il 405 è mai la risposta corretta che un'API dovrebbe inviare di proposito?

Sì. Se una risorsa supporta davvero solo la lettura, restituire 405 per un PUT o DELETE contro di essa è un comportamento REST corretto, ed è più informativo per chi chiama di quanto lo sarebbe un generico 404.

Un firewall o un WAF possono causare un 405?

È meno comune di una configurazione errata dell'applicazione o del proxy, ma alcuni set di regole WAF restringono i metodi permessi per percorso e risponderanno 405 o un blocco simile prima che la richiesta raggiunga affatto l'origine.

Perché l'header Allow a volte elenca metodi che ancora falliscono?

L'header Allow riflette per cosa è registrata la rotta, non necessariamente cosa è completamente implementato. Un metodo può essere dichiarato e restituire comunque un errore per altri motivi, come un'autorizzazione mancante, una volta superato il controllo del metodo.