依赖外部服务不可用时，REST服务应返回何种HTTP状态码？

这是分布式系统API开发里很常见的场景，我来一步步给你分析：

先明确HTTP 503的核心语义 #

HTTP 503 Service Unavailable 的官方定义是：服务器当前无法处理请求，通常是由于临时过载或维护，且该状态是暂时性的。

回到你的场景：服务A本身是正常运行的，但因为依赖的外部服务B不可用，导致A无法完成当前请求的全部业务逻辑。从客户端的视角来看，它向A发起请求，但A无法提供预期的服务——这种情况下，返回503是完全符合语义的。

你提到的“仅依赖的B不可用，A自身没问题”其实不影响503的合理性：客户端并不关心A内部的依赖关系，它只关心自己的请求能不能被处理。对这个请求来说，A的服务能力确实是暂时不可用的，所以503是合适的选择。

可选的优化点 #

使用503时，建议额外做这两件事：

• 在响应体里返回清晰的错误说明，比如 {"error": "依赖服务B暂时不可用，请稍后重试"}，让客户端能快速定位问题原因。
• 如果能预估B的恢复时间，加上 Retry-After 响应头（可以是具体的HTTP日期，或者秒数），帮助客户端合理安排重试逻辑。

要不要考虑其他状态码？ #

• 502 Bad Gateway：这个状态码适用于A作为网关/代理，转发请求到B时收到了无效响应的场景。如果A是直接调用B的业务服务，而非网关角色，502的语义就不太贴合，不建议使用。
• 4xx系列：绝对不适合，因为4xx是客户端错误范畴，而这里明显是服务端侧的依赖故障，属于服务端错误，必须用5xx系列状态码。

总结 #

优先选择返回503 Service Unavailable，配合清晰的错误信息和可选的Retry-After头，既符合HTTP标准语义，又能给客户端明确的指引。

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