HTTP API开发：资源不存在时应遵循什么状态码返回逻辑

官方规范的明确定义 #

HTTP 1.1 官方语义规范（RFC 7231）对两个状态码的适用场景没有歧义：

• 200 OK：代表请求被成功处理，服务器已经返回了请求所指向的目标资源。
• 404 Not Found：代表服务器无法找到当前请求对应的目标资源，无法确认该资源是否存在过，也没有可用的转发地址。

HTTP状态码的设计初衷是描述整个HTTP请求的最终处理结果，从来不是用来标记「API服务自身的代码有没有运行崩溃」——服务内部的运行健康度是监控系统要覆盖的指标，不属于HTTP协议层状态码的职责范围。

「200+响应体错误码」方案的来源 #

你提到的Elasticsearch等产品采用的200包装错误的实现，本质是历史遗留设计，并非REST架构的推荐实践：

• 早期很多RPC风格的接口为了规避网络链路中的拦截问题，会统一返回200状态码——早年部分运营商网络、企业网关、防火墙会对非200的响应做劫持、截断，甚至直接丢弃响应体，导致客户端拿不到完整的错误信息。
• Elasticsearch的这套逻辑从最早的版本沿用至今，核心是为了向后兼容老版本客户端，不是值得新接口参考的设计标准，其官方近年推出的新API也在逐步向标准HTTP状态码对齐。

实际开发的选择原则 #

你可以根据业务场景选择实现方式，但必须保证全接口的状态逻辑统一，不要同一套服务里部分接口用标准状态码、部分接口用200包装错误：

• 如果是严格REST风格的资源映射类接口（比如你提到的对象存储文件获取接口，URL和目标文件一一对应）：优先直接返回404状态码。这套语义是所有HTTP客户端、CDN、代理服务原生支持的，不需要额外解析响应体就能做错误提示、缓存降级、重试策略配置，也不会出现监控面板显示全是200成功请求、实际用户全部拿不到资源的统计失真问题。
• 如果你的服务有历史包袱，比如网关层强制要求所有响应必须返回200、或者要兼容老版本的客户端解析逻辑，可以采用200包装业务错误码的方案，但必须在接口文档中明确标注状态规则，同时在监控统计时把业务错误的请求从成功请求口径中剥离。

一个常见的认知误区：不少开发者认为「API代码正常执行完没有抛异常就该返回200」，这是混淆了服务内部执行状态和HTTP协议层响应状态的边界。代码正常运行、逻辑判断出资源不存在，这个请求的处理结果就是「未找到目标资源」，返回404完全符合语义；只有服务出现未捕获异常、依赖服务断连超时、无法正常处理请求的场景，才属于5xx类状态码的覆盖范围。

内容的提问来源于stack exchange，提问作者int 2Eh