HTTP 状态码表达通用类别，业务错误码表达具体原因，两者不应互相替代。客户端不应该解析中文错误信息来判断下一步动作。

{
  "code": "ORDER_ALREADY_PAID",
  "message": "订单已支付",
  "requestId": "01J..."
}

业务错误码一旦公开就形成契约，应保持稳定。错误信息可以调整和国际化，但不能包含堆栈、SQL、内部地址或敏感参数。

区分可重试性

参数错误和权限不足通常不应重试；临时过载、依赖超时可能重试。服务端可通过状态码和 Retry-After 提供提示，客户端则必须设置次数上限和退避。

所有错误响应携带请求 ID，可以把用户反馈连接到服务端日志和链路追踪。错误设计做好后，排障速度和客户端体验都会明显改善。