外部操作执行失败时，REST API应返回何种合适状态码？

问题背景 #

我的REST API会调用外部服务，该服务可能因各类原因失败。我想了解我的API应向客户端返回何种推荐状态码？500 Internal Server Error似乎并不合适：为何要为非我方原因的问题返回500？具体场景如下：

• 用户尝试下单
• 若订单无效，返回400
• 若订单有效，将其发送至可能失败的外部API
• 需向客户端返回合适的状态码

推荐状态码及适用场景 #

1. 502 Bad Gateway（网关错误）

当你的API作为中间节点，转发请求到外部服务时，遇到以下情况优先返回502：

• 外部服务完全无法连接（比如DNS解析失败、连接超时）
• 外部服务返回了非HTTP标准的无效响应（比如连接重置、空白响应）
  这个状态码的语义是“网关从上游服务器收到了无效响应”，精准对应第三方服务故障的场景，让客户端明确问题出在外部依赖，而非自身请求或你的服务内部。

2. 503 Service Unavailable（服务不可用）

如果能确定外部服务是暂时性不可用（比如正在维护、过载限流），返回503更合适。同时可以在响应头中添加Retry-After字段，告知客户端建议的重试时间（比如Retry-After: 300表示5分钟后重试）。这个状态码明确提示客户端：故障是临时的，稍后重试可能成功。

3. 为什么不使用500 Internal Server Error？

500 Internal Server Error的核心语义是“服务器内部出现未知错误”，通常用于你的服务自身逻辑错误（比如代码bug、数据库连接失败）、无法处理的异常场景。外部服务故障属于第三方可控范围外的问题，用502或503能更清晰地区分故障来源，帮助客户端做出正确的处理决策（比如自动重试、提示用户稍后操作）。

额外实践建议 #

• 在响应体中附带简洁的错误信息，例如：{"code": "external_service_failure", "message": "订单服务暂时无法访问，请稍后重试"}，方便客户端解析和给用户展示友好提示。
• 对于偶发的外部服务调用失败，可以在你的API中加入有限次数的重试机制（比如使用指数退避策略），减少直接返回错误给客户端的概率。

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