405 Method Not Allowed: causas y soluciones

Qué significa 405 Method Not Allowed

El RFC 9110 exige que una respuesta 405 incluya una cabecera Allow que liste los métodos que el recurso realmente admite. Esa cabecera es todo el diagnóstico en una línea: si una petición a /api/users devuelve 405 con Allow: GET, HEAD, la ruta existe y funciona bien para lectura, simplemente nunca tuvo un manejador conectado para el método que enviaste, sea cual sea.

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

Cómo aparece el error

Los navegadores muestran una página de error genérica para un 405 devuelto a una navegación normal, ya que no es un caso para el que tengan una gestión especial. Es mucho más habitual encontrarse un 405 en una pestaña de red, en una llamada AJAX fallida, o en un fallo de preflight de CORS en la consola, porque la mayoría de los 405 vienen de peticiones programadas y no de enlaces pulsados. Desde la línea de comandos, el método y la cabecera Allow cuentan toda la historia:

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

Qué causa un 405 Method Not Allowed

• Hacer POST a un archivo estático. Una petición a un archivo real en disco, como un PDF o una imagen, servido por un servidor web que solo responde a GET y HEAD para contenido estático.
• Llamar a una ruta que solo define algunos métodos. Una ruta de framework registrada solo para GET devuelve 405 para cualquier otro verbo, por diseño, en lugar de 404.
• Una petición OPTIONS de preflight de CORS rechazada. Los navegadores envían automáticamente una petición OPTIONS antes de ciertas llamadas de origen cruzado, y un servidor o gateway que no tiene manejador para OPTIONS en esa ruta responde 405, lo que luego se manifiesta en el navegador como una petición de origen cruzado bloqueada en lugar de un 405 claro.
• nginx sirviendo un bloque location pensado para archivos estáticos. Un bloque location que usa try_files contra el sistema de archivos sin proxy_pass devolverá 405 en POST, ya que servir archivos estáticos en nginx solo implementa GET, HEAD, y por defecto un conjunto limitado de métodos.
• Restricciones de verbos de WebDAV e IIS. IIS y algunos servidores con WebDAV habilitado usan listas blancas explícitas de verbos por ruta, y un método fuera de esa lista, incluidos otros personalizados como PROPFIND, recibe 405 aunque la ruta general funcione por lo demás.
• Una ruta de framework mal configurada. Una ruta pensada para aceptar tanto GET como POST pero registrada solo para uno, a menudo después de una refactorización que separó un manejador sin actualizar la declaración de la ruta.
• Una lista blanca de métodos de un balanceador de carga o un API gateway. Algunos gateways restringen los métodos permitidos por ruta con independencia de la aplicación, y la aplicación nunca llega siquiera a ver la petición rechazada.

Cómo saber de quién es la culpa

Un 405 es casi siempre un problema de configuración o de código del lado del servidor y no algo causado por un visitante, ya que los navegadores y los enlaces normales no envían métodos arbitrarios por su cuenta. Si una página funciona en general pero una acción concreta, como el envío de un formulario o una llamada a una API desde JavaScript del lado del cliente, falla con 405, revisa si el método de esa petición concreta coincide con lo que espera el endpoint. Si coincide y el error es nuevo, la forma más rápida de confirmar que se rompió una configuración de ruta o de proxy es ejecutar una comprobación HTTP que envíe el método exacto que usa tu aplicación y comparar el resultado en torno a un despliegue reciente.

Cómo corregir un 405 Method Not Allowed

Si eres el visitante

1. Recarga y vuelve a intentar la acción, ya que un 405 de un envío de formulario a veces puede venir de una página que cargó una versión antigua en caché del formulario apuntando al endpoint equivocado.
2. Borra la caché del navegador para el sitio si el problema persiste, por si un service worker obsoleto o una respuesta en caché está reproduciendo una petición antigua ya incompatible.
3. Repórtalo al sitio, ya que casi siempre es un problema de configuración de su lado; no hay ninguna solución del lado del cliente para un servidor que realmente no acepta ese método.

Si administras el sitio

1. Lee la cabecera Allow en tu propia respuesta 405 para confirmar exactamente qué métodos cree el servidor que son válidos para esa ruta, y luego compáralo con lo que el cliente realmente está enviando.
2. Añade el método que falta a la ruta. En la mayoría de los frameworks esto es una declaración de ruta de una línea; la solución rara vez está en la lógica de la aplicación una vez que sabes qué verbo falta.
3. Gestiona OPTIONS explícitamente en las rutas con CORS habilitado. O deja que el middleware de CORS de tu framework responda automáticamente a las peticiones de preflight, o añade un manejador que devuelva las cabeceras Allow y Access-Control-Allow-Methods correctas.
4. Corrige el bloque location de nginx si un bloque de archivos estáticos está capturando una ruta que necesita un backend. Un ejemplo mínimo que hace proxy del POST en lugar de servirlo como archivo:

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

5. Revisa las listas blancas de métodos del gateway y del balanceador de carga por separado de la aplicación, ya que una petición puede rechazarse antes de llegar siquiera a tu código, y los registros de la aplicación no mostrarán nada de ella.

Cómo prevenir un 405 silencioso tras un despliegue

Una ruta que pierde un método durante una refactorización, o una regla de proxy que empieza a interceptar una ruta que antes no interceptaba, no va a lanzar ninguna excepción en ningún sitio, simplemente va a responder con una respuesta HTTP incorrecta pero válida. Una comprobación HTTP programada con una aserción sobre el código de estado, enviada con el método exacto del que depende tu integración, detecta esa regresión justo después del despliegue que la causó en lugar de después de que los usuarios reporten formularios rotos. Para endpoints de API en concreto, la monitorización de API que comprueba tanto el método como el cuerpo de la respuesta confirma que la ruta no solo acepta la petición sino que también se sigue comportando correctamente.

Errores relacionados

Consulta 404 Not Found para una ruta que no existe en absoluto, a diferencia de una que existe pero rechaza el método, la guía de la familia 4xx para la familia completa, y 401 Unauthorized y 422 Unprocessable Content en otros sitios de esta tanda.

Preguntas frecuentes

¿Cuál es la diferencia entre 404 y 405?

404 significa que no existe nada en esa ruta para ningún método. 405 significa que la ruta existe y funciona para al menos un método, solo que no el que usaste, y la cabecera Allow confirma cuáles son válidos.

¿Por qué una petición CORS falla con algo que parece un 405?

Los navegadores envían automáticamente un preflight OPTIONS antes de muchas peticiones de origen cruzado. Si el servidor no tiene ningún manejador para OPTIONS en esa ruta, responde 405, y el navegador lo reporta como un fallo de CORS en la consola en lugar de mostrar directamente el código de estado en bruto.

¿Puede el 405 ser alguna vez la respuesta correcta que una API envíe a propósito?

Sí. Si un recurso genuinamente solo admite lectura, devolver 405 para un PUT o un DELETE contra él es un comportamiento REST correcto, y es más informativo para quien llama que un 404 genérico.

¿Puede un firewall o un WAF causar un 405?

Es menos habitual que una mala configuración de la aplicación o del proxy, pero algunos conjuntos de reglas de WAF restringen los métodos permitidos por ruta y responderán 405 o un bloqueo similar antes de que la petición llegue siquiera al origen.

¿Por qué la cabecera Allow a veces lista métodos que igualmente fallan?

La cabecera Allow refleja para qué está registrada la ruta, no necesariamente lo que está completamente implementado. Un método puede estar declarado y aun así devolver un error por otros motivos, como una autorización ausente, una vez que pasa la comprobación del método.