# 蓝牙设备检查的具体错误

2026-09-18 · 后端版本 `0.94.1-rc.ble-errors1` · 无数据库迁移。

覆盖 `POST /api/v1/mini/ble-device-state` 及小程序、网页的 `ble-bind-tokens`。原来的“设备不可用或当前账号没有设备管理权限”已拆成实际失败条件。未创建家庭、老人仍允许添加未归属的设备。

| HTTP | code | 原因 |
| --- | --- | --- |
| 400 | DEVICE_ID_INVALID | 设备编号格式不正确 |
| 404 | DEVICE_NOT_REGISTERED | 平台未找到设备注册记录 |
| 409 | DEVICE_NOT_RELEASED | 已登记，但未完成出厂放行 |
| 409 | DEVICE_ENROLLMENT_UNSUPPORTED | 未启用蓝牙实体确认绑定 |
| 403 | DEVICE_REVOKED | 设备被停用 |
| 403 | DEVICE_LOST | 设备被标记丢失 |
| 403 | DEVICE_QUARANTINED | 设备被隔离 |
| 403 | ACCOUNT_NOT_FOUND | 登录身份无对应平台账号 |
| 403 | ACCOUNT_DISABLED / ACCOUNT_DELETED | 账号已停用 / 已删除 |
| 403 | CUSTOMER_REQUIRED | 使用了管理账号，需切换家庭账号 |
| 403 | DEVICE_TENANT_MISMATCH | 设备不属于当前账号所在组织 |
| 403 | TENANT_INACTIVE | 设备所属组织已停用 |
| 403 | DEVICE_OWNED_BY_OTHER_ACCOUNT | 设备已添加到其他账号，需原账号操作或移除 |
| 403 | DEVICE_MANAGE_PERMISSION_REQUIRED | 已绑定家庭，当前账号无该家庭设备管理权限 |
| 409 | DEVICE_BINDING_STALE | 设备归属记录与当前状态不一致 |
| 409 | ALREADY_BOUND | 令牌申请时设备已有归属，无需重复添加，可重新配网 |
| 400 | ELDER_ID_INVALID | 令牌申请时显式传入的老人编号格式不正确 |

返回格式保持不变，示例：

```json
{
  "ok": false,
  "code": "DEVICE_NOT_RELEASED",
  "message": "设备已登记但尚未放行，请联系管理员完成出厂放行",
  "request_id": "与请求对应的追踪编号"
}
```

多项条件同时不满足时，先返回账号/组织准入问题，再返回设备状态与归属问题。不给出其他设备归属账号的姓名、手机号或老人资料。数据库、内部故障仍走服务器异常处理，不将原始 SQL、凭据或内部错误暴露给客户端。

小程序现有请求层和设备选择页面直接展示 message，已用回归测试验证具体提示能保留到界面、业务 403 不会清除登录。此提示调整无需更新小程序或设备固件；此前“先添加设备、后绑定老人”的新入口仍需发布新版小程序。

验证：独立 PostgreSQL/Redis 实跑完整 onboarding 集成测试，覆盖上述设备状态、账号、组织、账号归属、家庭权限、归属失效及真实 Mini HTTP 错误信封；小程序 103 项测试通过。