错误响应差异
HTTP status 与 JSON status 是两层信号。本手册 13 个端点全部位于 main 服务，出口形态以 main 服务实现为准。最重要的陷阱：认证失败也返回 HTTP 200，由 body status=1000 表达——这是兼容旧客户端的现行行为（服务端注释原文：「旧客户端沿用 HTTP 200 传输，由 body 1000 表达认证失败，不回传原始认证消息」）。HTTP 2xx 不代表请求成功。
认证失败族：200 / 1000
| 项 | 当前行为 |
|---|---|
| 触发 | 凭据缺失、过期、AES 解密或验签失败、未认证访问受保护端点（13 端点均不在白名单，最终进入 entry point） |
| HTTP / body status | 200 / 1000 |
| 字段 | error 为冻结的认证兼容常量 Full authentication is required to access this resource；过滤链与 entry point 出口不本地化、不回传原始异常消息 |
| 接入影响 | 不得当作网络错误重试；应引导用户重新登录获取新凭据 |
main 服务 MVC 边界捕获的认证异常另有 401 / 1000 出口（尝试填充 localizedError）：同一失败族（认证族响应）在不同出口的传输状态可能不同，判定必须解析 body status，不能只看 HTTP。error 兼容常量同时是存量消费端的会话失效字符串判定依据与 app 端 localizedError 的翻译查找键，措辞永久冻结；status=1000 这类机器判定码是新消费端判定的首选依据。全局另有 200 / 1001 权限拒绝出口，但 13 端点均无细粒度权限注解，正常调用面没有已知触发点。
业务失败族
| 项 | 当前行为 |
|---|---|
| 触发 | 业务规则拒绝（ApiException），如授权码非法、库存租户禁绑、设备已绑定/已被他人绑定 |
| HTTP / body status | 200 / ex.status；默认，仅显式 null 时回退 |
| 字段 | error 为异常消息原文，保留 extraData；main Advice 尝试本地化 |
| 接入影响 | 与认证失败同为 HTTP 200，必须按 status 区分： 走重新登录； 族按操作页错误文案提示用户 |
协议错误与服务器错误
| 出口 | 触发 | HTTP / body status |
|---|---|---|
| 请求解析与校验 | body 转换、参数绑定、Bean Validation、constraint violation | 400 / 1002、 或 |
| 路由与媒体类型 | 路径不存在 / 方法不支持 / Content-Type 不支持 | 404 / 1008、405 / 1006、415 / 1007 |
| 未处理技术异常 | 服务端技术失败 | 500 / 500 |
localizedError 由 main Advice 尝试填充且可能为空；它只是展示辅助，判定依据始终是 status 与 error。
开发者判定口径
区分业务失败与网络/服务器错误的顺序：
- 响应不可达或非 JSON（超时、DNS 失败、网关错误页）→ 网络/部署层故障，可提示网络问题或安排幂等重试。
- HTTP 200 → 必须解析 body
status： 成功； 认证失败 → 重新登录，不是网络错误； 等业务码 → 业务失败，按操作页错误文案提示；未知业务码保留兜底分支。 - HTTP 400/404/405/415 → 协议错误（客户端实现问题），不是用户可自行恢复的业务失败。
- HTTP 500 → 服务端技术失败，写操作不应静默自动重试。
不能把「HTTP 200」当成功，也不能把认证失败当网络错误反复重试。业务失败的具体错误码清单由各操作页与其链接的业务页给出，本页只约定出口形态；机构侧全量错误出口对照另见机构错误响应差异。
依据
适用后端基线：源码归纳 @ 2026-09-14。各出口的语义归纳：认证失败经认证过滤链按 200/1000 兼容形态返回（entry point 与 denied handler 分别对应未认证/已认证无权限两类）；统一异常出口把认证/权限/业务拒绝/请求校验与技术异常分别映射到 401/1000、403/1001、422（业务拒绝默认）、400/1000/500 族；localizedError 由统一异常出口填充本地化文案；机器判定以 status 数值与 error 文本为准。