结论先行：错误响应体不是「给人看的道歉信」，而是「给客户端机器读的决策信号」。服务端怎么设计这个 body，直接决定了客户端能不能正确做三件事——该不该重试、该不该降级、该不该把提示透传给用户。我做了 10 年技术 PM，经手过 3 起「服务端把错误体设计得含糊、客户端 SDK 跟着做错决策」的事故，根因没有一起是客户端的 bug，全是服务端「错误体没当契约管」。这篇给一份服务端可直接抄的清单：状态码怎么选、业务 code 怎么命名、Retry-After 什么时候必须给、traceId 放哪。
一、现象：一个含糊的 500，让 SDK 把写接口重试了 6 次
先摆数字。去年我们一个 B 端结算平台（日均 3.1 万笔结算，客户端是团队自研 Java SDK，底层 OkHttp 4.12），后端某次依赖的第三方风控接口超时，后端把异常兜底成「HTTP 500 + message=系统繁忙，请稍后再试」，没带任何业务 code、没带 Retry-After、traceId 埋在网关日志里没吐到 body。
SDK 侧的默认逻辑是「5xx 且无明确 code → 视为可重试 → 退避 1s/2s/4s 重试 3 次」。结果一次 30 秒的第三方抖动：
/api/v1/settlements（创建结算单，写接口）收到 4,203 次重试请求，其中 312 次落到了「已落库但响应没回来」的结算单上——同一笔结算单被建了两次，涉及 19 个企业客户，财务对账花了 1.5 个工作日；- 更隐蔽的：因为 message 统一是「系统繁忙」，客服拿到工单后完全没法告诉用户「是风控的问题」还是「是系统挂了」，只能回「请稍后再试」，投诉率当天从 0.2% 涨到 1.7%；
- 事后复盘，客户端 SDK 团队说「我们重试逻辑没错，是你们把 500 当万能码用了」。但真正该背锅的是服务端：错误体没给客户端任何「这是写接口、结果未知、别瞎重试」的信号。
二、原理：错误体是契约，而且和 HSTS 一样「发出去就收不回来」
这里要把两个常被混为一谈的东西拆开：
- HTTP 状态码是「给路由器和客户端做粗粒度决策的信号」——429 告诉客户端「限流了，退避再来」，500 告诉客户端「服务端出错了」。它决定了能不能重试、走不走降级。
- 响应体里的业务 code是「给业务层做细粒度决策的信号」——同样是 500，
SETTLE_RISK_TIMEOUT（风控超时）和SETTLE_DB_DEADLOCK（死锁）的处理方式完全不同：前者该退避重试，后者该立即失败转人工。
关键在于：错误体一旦下发给客户端 SDK，就是一个「契约」。客户端会按你给的结构去解析、去分支。这和站内讲安全响应头那篇的道理是同构的——HSTS 头一旦下发就无法撤销；同理，你错误体里的字段结构、code 语义一旦让 12 个下游 SDK 依赖上了，你再改字段名、改 code 含义，就是「改契约」，代价是「全量下游升级」，比 HSTS 还难收。
所以错误体设计的核心原则不是「怎么写得好看」，而是**「怎么让客户端机器能无歧义地做出正确决策，且这个语义一旦定下就稳定」**。
三、具体做法：一套可直接抄的错误体 schema 与映射表
我团队现在强制所有对外接口用这套结构（JSON，兼容 Spring Boot 3.2 全局异常处理器）：
{
"error": {
"code": "SETTLE.RISK_TIMEOUT", // 业务 code：稳定、机器可读、点分层级
"status": 504, // 与 HTTP 状态码一致，方便网关/SDK 粗判
"message": "Risk engine timed out, request not processed", // 给人看，不泄露内部细节
"retryable": false, // 显式告诉客户端：别重试
"retry_after_ms": 2000, // 若 retryable=true，给精确退避
"trace_id": "a1b2c3d4e5f6", // 排障锚点，必须吐到 body
"timestamp": "2026-10-22T06:33:07Z"
}
}
配套三条硬规则：
规则 1：状态码只表达「网络/协议层语义」，业务细节放 code。
- 4xx：请求本身有问题，明确不可重试（400 参数错、401 鉴权、403 无权限、422 业务校验失败）。
- 429：限流，必须带
Retry-After（秒或 HTTP 日期），且retryable=true。 - 5xx：服务端故障，但必须细分——503「过载，退避可重试」、504「下游超时，结果未知，写接口不可重试」、500「未分类，默认不可重试」。
- 关键：写接口超时一律 504 +
retryable:false，把「结果未知」这个信号显式吐给客户端，而不是让客户端拿一个裸 500 去猜。
规则 2：业务 code 用「域.场景」点分层级，且语义只增不改。
SETTLE.RISK_TIMEOUT、PAY.IDEMPOTENT_CONFLICT、ORDER.STOCK_EMPTY。- 一旦某个 code 发布给下游，它的语义就冻结：可以新增 code，不能改已有 code 的含义；废弃要留 90 天兼容窗口并双吐新旧 code。
规则 3：retryable 是服务端替客户端做的决策，别把判断留给客户端。
- 客户端 SDK 不该自己维护「哪些 code 能重试」的白名单——那正是 id=2060 那篇讲的、客户端侧最容易出错的地方。服务端在 body 里直接给
retryable+retry_after_ms，客户端只管执行。把「能不能重试」的判断权，从 12 个各写各的 SDK 收敛到服务端一处。
四、踩过的坑与反直觉之处
坑 1：message 写得太「友好」，反而泄露信息。 我们早期 message 是「风控服务 10.20.33.7:8080 连接超时」，被安全同学抓到——内部 IP + 端口全吐给了外部调用方。教训：message 只说「发生了什么类别的事」，具体 IP/端口/表名/SQL 一律进服务端日志，靠 trace_id 去查。
坑 2：错误体加字段，老 SDK 直接反序列化崩。 我们给 body 加 retry_after_ms 时，有个 2021 年的老 SDK 用的是严格模式 JSON 解析（FAIL_ON_UNKNOWN_PROPERTIES=true），新字段直接抛异常，把「能重试」的请求全变成了「硬失败」。教训：错误体新增字段必须走灰度，且客户端默认用宽松解析——这点比成功响应体更该被重视，因为错误路径平时不跑，一旦跑就全量炸。
坑 3：同一个 code，换个端点语义就变了。 我们把 STOCK_EMPTY 既用在「下单扣库存」也用在「购物车查库存」——前者是「该失败」，后者是「该返回空列表」，但客户端拿到同一个 code 没法区分。教训：code 语义要绑定端点，最好带端点前缀，或在契约文档里逐端点声明。
一个我想抛给社区讨论的开放问题：retryable 这种「服务端替客户端做决策」的字段，会不会让客户端团队丧失了对自己重试策略的掌控？ 我现在的立场是「写接口该服务端说了算，读接口可下放」，但边界到底画在哪，欢迎大家拍砖。
五、结论与可复用清单
- 错误体是契约，不是文案：一旦让下游 SDK 依赖，语义就冻结，改字段 = 全量下游升级。
- 状态码管「能不能重试/降级」，业务 code 管「具体怎么分支」，两层各司其职，别混在一个字段里。
- 写接口超时 = 504 +
retryable:false，把「结果未知」显式吐给客户端，别用裸 500 让客户端猜。 - 429 必须带
Retry-After，否则客户端只能瞎猜退避，把「一次限流」放大成「一片 429」（站内讲 NTP 时钟跳变那次 19000 个 429 的复盘，根子之一就是客户端拿不到精确退避信号）。 retryable由服务端显式给出，把重试决策权从 N 个各写各的 SDK 收敛到服务端一处。- trace_id 必须进 body，message 只说类别不泄露内部细节，错误体加字段走灰度 + 客户端宽松解析。
一句话收尾：别把错误体当「出事了写句抱歉」，要当「给机器读的决策接口」来设计——它的质量，决定了你下游 12 个客户端在故障时刻是帮你止血，还是帮你放血。