REST API错误信息传递的最佳实践咨询

我完全理解你在REST API里处理错误信息时的困惑——确实没有一套完全统一的官方指南，尤其是像403这类状态码需要返回更具体的提示（比如“你的账户已被禁用”）的时候，选哪种方式很纠结。

你提到的几个方案我都接触过，给你梳理下各自的特点：

• SOAP风格的响应体扩展：在响应体里额外加errorMessage这类字段，不光返回业务模型。这种方式很直观，客户端解析起来也简单，但缺点是打破了“成功响应体返回业务模型，错误返回不同结构”的一致性，有点背离REST以资源为核心的理念。
• 自定义响应头：给4xx/5xx这类错误状态码加个errorMessage的额外响应头。好处是不会污染响应体，但问题在于HTTP头的长度有限制，而且有些客户端框架对自定义头的支持可能有坑，另外也不符合常规的错误信息传递习惯，开发者排查问题时可能第一时间不会去看响应头。
• 统一错误响应体：所有错误请求都返回固定结构的错误体，替代成功时的业务模型。这应该是目前最主流的REST实践了，比如常见的结构可能是：

  {
    "code": "ACCOUNT_DISABLED",
    "message": "你的账户已被禁用",
    "details": []
  }
  

  这种方式保持了错误响应的一致性，客户端可以统一处理错误逻辑，也能传递足够的细节，非常推荐。
• 自定义HTTP状态短语：把状态码旁边的默认短语（比如403对应的"Forbidden"）换成自定义字符串。你觉得这个最符合REST风格，但确实有个关键问题：HTTP协议虽然允许自定义状态短语，但很多HTTP客户端、代理服务器或者日志系统会忽略甚至不处理自定义短语，它们只会识别状态码。比如有些客户端库拿到响应后，只会返回状态码，状态短语直接被丢弃，你的自定义提示就完全没用了。而且不同服务器对自定义状态短语的支持也有差异，兼容性是个大隐患。

所以综合来看，统一错误响应体是最稳妥、最符合现代REST实践的方案，既能清晰传递错误信息，又能保证客户端处理的一致性。

备注：内容来源于stack exchange，提问作者Alessandro Scarozza