构建API时，响应JSON的错误消息字段是否有行业标准？

我正在构建后端API，想了解错误JSON响应对象的字段最佳格式。FastAPI的返回示例有如下两种：

{
    "message": "Some error"
}

{
    "detail": "Some error"
}

根据我的经验，通常取决于前端需求，但我想知道是否存在首选的行业实践。我查阅了一些资料，但未找到明确标准，包括：

• RFC 9110 错误处理相关内容
• API错误处理最佳实践相关博客
• Stack Overflow上的相关回答（仅关注对象中的字段，不涉及底层协议）

行业实践总结 #

没有绝对统一的强制标准，但有几个被广泛接受的实践方向：

1. 对齐框架默认行为
   FastAPI内置错误响应（如404、422参数校验失败）默认使用detail字段。基于FastAPI开发时优先用detail，能减少自定义错误处理的工作量，保持和框架生态的一致性，避免前后端额外适配成本。

2. 字段语义清晰且全API统一
   不管选message还是detail，核心是全项目接口统一使用同名字段，不能出现部分接口用message、部分用detail的混乱情况。同时字段名要匹配语义：

• message更偏向用户友好的提示（适合直接展示给终端用户）
• detail更偏向技术细节（适合开发排查，可包含参数校验失败的字段明细等具体信息）

3. 扩展字段增强实用性
   生产环境的错误响应建议补充更多字段，提升可维护性和前端处理效率：

• error_code：自定义业务错误码（如INVALID_PARAM、AUTH_FAILED），方便前端快速判断错误类型并做针对性处理
• timestamp：错误发生的时间戳
• status_code：对应HTTP状态码（和响应头状态码保持一致，方便前端统一解析）

示例扩展响应：

{
    "error_code": "INVALID_PARAM",
    "detail": "参数username不能为空",
    "status_code": 400,
    "timestamp": 1718000000
}

4. 优先遵循团队协作规范
   如果前端团队已有约定的错误字段格式，直接遵循团队规范即可——API的最终目的是服务于前后端协作，统一的格式能大幅提升开发效率。

内容的提问来源于stack exchange，提问作者engineer-x