双重表达：HTTP 状态码 + 业务码

每个响应的结果由两层共同表达，客户端应以业务码 code 分支、以 HTTP 状态码做传输层判断：

• HTTP 状态码：表达请求在协议层的处理结果（200/401/404/422/429/500...）；
• 业务码 code：表达业务语义（OK、UNAUTHORIZED、NOT_FOUND...），成功恒为 OK。

失败响应结构（与成功同信封）：

{
  "code": "VALIDATION_FAILED",
  "message": "手机号不能为空",
  "data": {},
  "errors": { "mobile": "手机号不能为空" },
  "request_id": "9f2a5c8e1b3d7f40"
}

errors 与 data 的分工：

业务码（code）全集

业务码字符串是对外契约：客户端可硬编码这些值做分支，服务端只会在末尾追加新码，不会改名。新增码会通过文档与发版说明同步。

HTTP 状态码行为说明

405 示例（用 GET 调了一个只支持 POST 的接口）：

{
  "code": "NOT_FOUND",
  "message": "Method Not Allowed",
  "data": { "allow": ["POST"] },
  "errors": {},
  "request_id": "9f2a5c8e1b3d7f40"
}

限流（429）

以下接口按客户端 IP 定向限流，超限返回 429 RATE_LIMITED 并带 Retry-After 响应头（单位：秒，表示最早可重试时间）：

HTTP/1.1 429 Too Many Requests
Retry-After: 37
Content-Type: application/json; charset=utf-8

{
  "code": "RATE_LIMITED",
  "message": "请求过于频繁，请稍后再试",
  "data": {},
  "errors": {},
  "request_id": "9f2a5c8e1b3d7f40"
}

完整配额表：

重试约定：收到 429 后应读取 Retry-After 秒数做退避；不要立即重试。前端对表单类接口（登录/注册）建议在按钮上做倒计时提示。

除上表外，公共匿名写接口在各控制器业务层还有一层按 IP 的"灌水"防护（isWaterByIp），两者互补：中间件拦高频，业务层拦内容灌水。

排查建议

1. 先看 code 与 errors：表单类问题基本都由 errors 定位到具体字段；
2. 记录 request_id：只要把该 ID 提供给服务端，即可在日志中定位完整请求链路；
3. 区分 401 的两种子态：UNAUTHORIZED 是令牌无效（清令牌重登）；若未来收到 AUTH_REQUIRED 且有 data.jump_url，可直接跳转该地址登录；
4. 405 时看 data.allow：确认自己用的 HTTP 方法是否与文档一致（注意方法伪装 _method / X-HTTP-Method-Override 是否拼写正确）。