错误响应体如何设计

好的错误体同时服务三类读者：客户端代码（分支与重试）、值班的工程师（定位）、偶尔读日志的产品同学（理解影响面）。尽量稳定字段名，避免把堆栈直接吐给公网。

建议字段

• code：稳定、可枚举的机器码（如 INVALID_ARGUMENT），勿与 HTTP status 一一混用但可对应文档章节。
• message：给人看的短句，避免泄露内部主机名或 SQL。
• request_id：贯穿网关与下游，便于从用户截图反查日志。
• details（可选）：字段级校验错误数组，元素含 field、reason。

HTTP 状态码

4xx 表示调用方可修正的请求问题，5xx 表示服务方应处理。不要把「业务不允许」一律映射成 500；也避免用 200 包裹错误 JSON，除非你有极强的遗留约束并在文档中醒目标注。

与 JSON 工具页配合：在文档中贴出错误 JSON 样例，联调时可直接粘贴进本站 JSON 格式化页检查层级与字段拼写。