构建REST API端点：调用第三方服务时应返回何种HTTP状态码？

这是个非常典型的代理服务状态码设计问题，我来分享下行业里常用的两种思路，你可以根据自己的API定位来选择：

思路1：透传第三方服务的状态码 #

如果你的API核心定位就是透明转发第三方服务的请求与响应，让调用者能直接感知到第三方服务的真实状态，那直接返回第三方的状态码是最合理的选择：

• 当第三方返回200时，你的API也返回200+原响应内容；
• 当第三方返回404时，你的API同样返回404，哪怕响应体为空——如果需要更友好，你可以在响应体里补充一句说明，比如{"message": "第三方服务返回404：指定资源未找到"}；
• 对于第三方的5xx类错误（比如服务器宕机），你可以选择透传5xx，或者返回502 Bad Gateway（表示作为网关/代理的你的API无法从第三方获取有效响应），后者在网关类服务里更常见。

这种方式的好处是完全透明，调用者可以根据第三方的状态码做对应的业务逻辑处理，适合需要暴露底层服务状态的场景。

思路2：统一返回200，在响应体内封装第三方状态 #

如果你的API希望对外提供一个稳定的封装层，不想让调用者处理第三方服务的各种异常状态，那可以选择统一返回200，同时在响应体里结构化返回第三方的状态信息：
比如你的响应体可以设计成这样：

{
  "success": true,
  "third_party_status": 404,
  "third_party_data": "",
  "message": "第三方服务未找到请求的资源"
}

这里的success表示你的API本身成功完成了“调用第三方并获取结果”的任务，而third_party_status才是第三方服务的真实状态。

这种方式的好处是对外接口更稳定，调用者不需要处理各种非200的状态码，只需要解析响应体内的业务数据即可，适合作为上层服务给前端或其他业务系统调用的场景。

关键决策依据 #

最终选哪种方式，核心取决于你的API的设计目标和调用者的需求：

• 如果调用者需要知道第三方服务的真实状态（比如他们自己要和第三方服务交互），选透传；
• 如果调用者只关心你的API是否完成了任务，不需要感知底层细节，选封装返回。

另外，不管选哪种方式，一定要在你的API文档里明确说明状态码的返回规则，避免调用者产生困惑~

内容的提问来源于stack exchange，提问作者djm.im