服务器调用第三方服务（如AWS S3）失败时应返回何种HTTP状态码？

针对你的场景，优先推荐503 Service Unavailable，其次可考虑500 Internal Server Error，而你提到的502并不适用，具体分析如下：

• 排除502 Bad Gateway的原因
  502的语义明确指向“服务器作为网关或代理时，收到了上游服务器的无效响应”。你的服务器并非单纯的请求转发代理，而是包含独立业务逻辑（请求内容处理、数据库调用）的服务节点，使用502会误导客户端对服务角色的认知，语义不匹配。

• 推荐503 Service Unavailable
  这个状态码用于表示服务器暂时无法处理请求，场景包括自身过载、维护，或是依赖的第三方服务临时不可用。你可以搭配Retry-After响应头告知客户端重试时机，同时在响应体中明确说明“请求失败源于AWS S3服务调用失败”，让客户端清晰知晓故障原因。

• 备选500 Internal Server Error
  如果S3调用失败是不可恢复的（比如权限配置错误导致永久失败），或是你不需要区分第三方依赖故障的特殊性，500作为通用的服务器内部错误状态码也符合场景。但它的语义不如503精准，无法传递“临时不可用”的信号。

实践建议 #

无论选择哪种状态码，都要在响应体中返回明确的错误描述，比如：

{"error": "请求处理失败，原因是依赖的AWS S3服务调用失败"}

内容的提问来源于stack exchange，提问作者J. Hesters