HTTP 404响应码使用争议：请求体ID不存在应返回404还是400？

在处理一个支持提交多集合项目的API时，我们团队对响应码的使用产生了分歧：当请求体中的业务部门ID、原始站点ID或目标站点ID在数据库无匹配记录时，到底该返回404还是400？

双方观点 #

• 返回404的思路：
  这类场景本质是指定的业务资源未找到，虽然请求路由是正确的，但请求指向的具体资源（如对应ID的站点）确实不存在，符合HTTP 404 "Not Found"的语义——服务器无法找到请求的目标资源。同时在响应体返回明确提示（如No sites could be found with the id {id}），能让调用方直接定位问题根源。

• 返回400的思路：
  认为404仅适用于路由不存在的情况（比如请求/usr/10/resetPassword而非正确的/user/10/resetPassword），请求体中的ID无效属于"错误的请求参数"，符合HTTP 400 "Bad Request"的语义——服务器无法处理该请求，因为请求参数不符合预期。

分析与建议 #

HTTP规范并没有严格将404限定为路由错误，核心判断标准是错误的本质：

• 如果请求的核心目的是操作某个特定业务资源（比如通过站点ID关联项目），而该资源不存在，返回404更贴合语义，因为问题根源是资源缺失，而非请求格式或语法错误。
• 如果是请求体格式错误（比如ID格式不符合要求，如传入字符串而非数字），此时返回400才是合理的。

实际落地中，团队内部统一规范比纠结语义细节更重要：

1. 无论选择哪种方案，都要在API文档中明确标注不同错误场景对应的响应码和提示信息。
2. 保持一致性：同类错误场景统一使用相同的响应码，避免调用方对接时产生混淆。

回到示例场景，请求体中的站点ID不存在属于"业务资源缺失"，返回404并补充具体ID的提示信息，能让调用方更清晰地理解问题，是更合适的选择。

内容的提问来源于stack exchange，提问作者HansBakn