HTTP 501 Not Implemented: qué significa y cómo solucionarlo

Qué significa este error y cómo reconocerlo

• Un navegador, cliente de API, servicio de monitorización o comprobador HTTP recibe 501 Not Implemented.
• La respuesta puede producirse únicamente para una URL, un método HTTP, una funcionalidad del protocolo o un formato de solicitud concretos.
• Otras páginas o endpoints de API pueden seguir funcionando con normalidad.
• Las cabeceras de respuesta pueden identificar el servidor o intermediario, y mostrar información relacionada con la caché, la autenticación, las redirecciones o el proxy.
• En una solicitud HTTPS, recibir un HTTP 501 significa que la solicitud llegó a un endpoint que habla HTTP después de completarse las capas de conexión necesarias para esa solicitud; no demuestra que todas las rutas de DNS, TLS o red estén funcionando correctamente.

Causas principales, ordenadas por probabilidad

Causas probables, de las más específicas a las menos comunes

1. La funcionalidad HTTP solicitada no es compatible. Es posible que el servidor o la aplicación no implemente el método, el comportamiento del protocolo, la funcionalidad de la solicitud o la capacidad de la ruta que se está solicitando.
2. Una ruta o un método está asignado a un handler no compatible. Por ejemplo, una implementación puede exponer una ruta, pero no conectarla con la lógica de aplicación destinada a procesar esa solicitud.
3. Un reverse proxy, CDN, WAF o gateway generó la respuesta. Un intermediario puede rechazar o decidir no procesar una solicitud antes de que llegue a la aplicación.
4. Los cambios de configuración o de implementación alteraron el procesamiento de las solicitudes. Los cambios en el enrutamiento, el proxy, el servidor o la aplicación pueden hacer que una solicitud que antes era compatible deje de estar disponible.
5. La solicitud no coincide con el contrato compatible del endpoint. Un método inusual, un detalle del protocolo, un tipo de contenido o un formato de solicitud pueden revelar una ruta de código no compatible. Confirma el comportamiento documentado del endpoint en lugar de asumir que toda discrepancia en una solicitud debe etiquetarse como 501.

Los fallos de autenticación, los fallos de autorización, los límites de frecuencia y las solicitudes mal formadas suelen utilizar otros códigos de estado. Inspecciona la respuesta completa y los registros antes de considerarlos la causa de un 501.

Cómo solucionarlo

Si eres visitante o consumidor de una API

1. Reintenta una vez la URL exacta y comprueba que la dirección, la ruta, los parámetros de consulta y el método de solicitud sean correctos.
2. Si el endpoint normalmente requiere una cuenta, inicia sesión mediante el proceso habitual del sitio y vuelve a intentarlo. No envíes credenciales a un endpoint desconocido.
3. Si utilizas un cliente de API, compara el método y el formato de la solicitud con la documentación del endpoint. Una visita desde un navegador puede usar GET, mientras que una operación de API puede requerir otro método.
4. Revisa las cabeceras y el cuerpo de la respuesta en busca de indicios relacionados con el servidor, el proxy, la autenticación, las redirecciones o la caché. No expongas cookies, cabeceras de autorización, claves de API ni otros secretos al compartir información de diagnóstico.
5. Evita los reintentos repetidos si el servicio está fallando o indica que se ha alcanzado un límite. Registra la URL, el método, la hora aproximada, el estado de la respuesta y una copia depurada de las cabeceras relevantes.
6. Si el error persiste, envía esos datos al propietario del sitio o de la API. Solo el operador del servicio que responde puede corregir una función no compatible del lado del servidor.

Si eres propietario del sitio web o de la API

1. Captura la solicitud exacta que falla. Registra el método HTTP, la URL, los parámetros de consulta, las cabeceras de solicitud relevantes para el enrutamiento, el estado, las cabeceras de respuesta y un cuerpo de respuesta depurado. Compárala con una solicitud que funcione.
2. Determina si el comportamiento es intencionado. Comprueba si la ruta y el método deben ser compatibles. Si el método está prohibido en lugar de no estar implementado, la respuesta prevista puede ser otro estado, como 405; utiliza el contrato y la implementación reales del servicio como referencia.
3. Identifica la capa que produce la respuesta. Comprueba si el 501 procede de la aplicación, el web server, el reverse proxy, la CDN, el WAF, el API gateway u otro intermediario. Una cabecera por sí sola puede ser solo indicativa, así que confírmalo con registros que incluyan marcas de tiempo.
4. Inspecciona los registros correspondientes. Busca en cada capa relevante la misma hora de la solicitud, ruta, método, identificador de solicitud y resultado del upstream. Empieza por el componente más externo y sigue la solicitud hacia la aplicación.
5. Revisa los cambios recientes. Compara las implementaciones y los cambios realizados en el enrutamiento, los módulos del servidor, las reglas del proxy, los handlers de la API, el comportamiento de la CDN, las políticas del WAF y la configuración del protocolo. Céntrate en los cambios que afecten a la ruta o al método que falla.
6. Reproduce el problema con la solicitud segura más pequeña posible. Elimina las cabeceras y los campos de carga innecesarios, pero conserva el método y la ruta necesarios para activar el problema. Cuando sea posible, prueba primero en un entorno no productivo autorizado.
7. Aplica la corrección más específica. Restaura el handler previsto o ajusta la regla concreta de la ruta o del intermediario. Evita cambios generales de seguridad, autenticación, permisos o proxy, salvo que los registros demuestren que son directamente responsables y el cambio haya sido autorizado.
8. Vuelve a probar la solicitud original y el comportamiento relacionado. Confirma el estado, el cuerpo de respuesta y las cabeceras esperados para la solicitud que falla; después prueba rutas y métodos relacionados para asegurarte de que la corrección no haya creado un problema más amplio.
9. Documenta el comportamiento intencionado. Si el 501 es esperado para una funcionalidad no compatible, registra los métodos compatibles y el comportamiento visible para el cliente, de modo que la monitorización y los usuarios no interpreten la respuesta como una interrupción inexplicada.

Prevención y cómo verificar la solución

• Monitoriza las tasas de estados HTTP por ruta, método e implementación, en lugar de realizar un seguimiento únicamente de la disponibilidad general.
• Mantén bajo control de versiones la configuración del enrutamiento de la aplicación, el web server, el proxy, la CDN, el WAF y el gateway.
• Prueba los métodos HTTP compatibles y las rutas importantes de la API después de las versiones y de los cambios de configuración de los intermediarios.
• Documenta qué rutas y métodos no son compatibles de forma intencionada, incluida la respuesta prevista para el cliente.
• Conserva los registros correlacionados y los identificadores de solicitud durante el tiempo suficiente para relacionar una respuesta con la capa que la produjo.
• Utiliza comprobaciones de estado que prueben la ruta y el método reales que necesitan los clientes importantes, no solo una solicitud genérica a la página de inicio.

Preguntas frecuentes