依赖第三方服务且其返回无效时，Rest API应返回何种状态码？

这确实是个挺常见的棘手场景，我来分享几个业界常用的方案，你可以根据自己API的语义和客户端的适配情况来选：

首选：502 Bad Gateway #

这绝对是最贴合你场景的标准HTTP状态码。HTTP规范里明确定义它的适用场景是：服务器作为网关或代理，从上游（也就是你依赖的第三方服务）收到了无效的响应。

你的API在这里刚好扮演了客户端和第三方服务之间的“网关”角色，当第三方返回无效结果时，返回502完全符合语义——既不会像500那样模糊地表示“内部错误”，也不会像400那样让客户端误以为是自己的请求出了问题。同时你可以在响应体里附上更具体的信息，比如：

{
  "error": "第三方用户服务返回无效结果",
  "details": "预期返回用户ID列表，但收到空值"
}

备选：422 Unprocessable Entity #

如果你的API更偏向于从业务层面定义错误，而非严格遵循网关类场景的状态码，也可以考虑422。这个码通常用于“请求格式正确，但业务逻辑无法处理”的情况——虽然用户的请求本身没问题，但因为依赖服务的异常导致你无法完成用户的请求，从业务视角看属于“无法处理该请求”。

不过这里要注意：一定要在响应体里明确说明错误根源是第三方服务，避免客户端误解是自己的请求参数有问题。

不推荐：自定义状态码 #

有些团队会想着用500的子状态码（比如500-3）来区分这类场景，但我不建议这么做——标准状态码的兼容性更好，绝大多数客户端框架都能识别502这类标准码并做出相应的错误处理逻辑，自定义码反而会增加客户端的适配成本。

总结下来，优先用502 Bad Gateway，这是最符合HTTP语义且清晰的选择。

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