HTTP 501 Not Implemented

HTTP 501 的含义

HTTP 501 Not Implemented 表示服务器无法识别或不支持完成该请求所需的功能。规范主要将其保留给无法识别的 HTTP 方法——服务器无法为任何资源处理该方法，这与 405 不同：在 405 中，方法本身是已知的，只是不允许用于该 URL。

在实践中，501 也常出现在代理和遗留服务器上，它们收到了自己从未被设计用来处理的请求（如 WebDAV 方法、旧技术栈上的 PATCH），或者作为配置了一半的后端的占位响应。

501 错误的常见原因

• 服务器完全未实现的 HTTP 方法（例如旧服务器上的 PATCH 或 WebDAV 方法）。
• 代理或网关收到了一个它无法转发的请求方法。
• 在实现完成之前就已部署的桩（stub）端点。
• 来自有缺陷客户端的格式错误的方法名（例如 GETT 这类拼写错误）。

作为开发者该如何修复

• 检查实际发送的方法——拼写错误和大小写错误的自定义动词其实相当常见。
• 如果该方法是合法的（例如 PATCH），请升级或配置服务器/框架以支持它，或者在技术栈允许的情况下，通过带有覆盖头的 POST 进行隧道传输。
• 要与 405 区分开：如果只有一个路由拒绝该方法，那就修复该路由（属于 405 的范畴）；如果整个服务器都拒绝，那就是平台层面的能力缺口。
• 不要在生产环境的 API 中为未完成的功能返回 501——由于 501 默认是可缓存的，建议优先使用 404 或功能开关（feature flag）。

示例响应

HTTP/1.1 501 Not Implemented
Content-Type: application/json

{"error":"not_implemented","message":"PATCH is not supported by this server"}

常见问题