错误码与排障
错误码与排障
Open-PicDecode 涉及三层错误：HTTP 接口统一码、OpenAPI / 业务码、原生解密 SDK 码（日志中可见，不一定全部映射到 HTTP 响应）。
HTTP 接口层（ApiResult）
| code | desc（默认） | 常见原因 |
|---|---|---|
| 200 | success | 解密成功，data.decodePic 有效 |
| 404 | param invalid / 字段提示 | JSON 缺字段、body 无法解析、校验失败 |
| 500 | error | 未捕获异常 |
成功判定：code == 200 且 data.decodePic 非空。
SDK 码映射到 HTTP body
LechangeEncryptUtil 在密钥错误、URL 不匹配等分支可能 throw new BusinessException(String.valueOf(sdkCode), …)，GlobalExceptionHandler 将 原生 SDK 码（如 2、-2）直接写入 JSON code，不一定统一为 1109。排障时须同时看 body code 与下文 SDK 码表。
OpenAPI 与业务码（BusinessException）
来自 Const.OpenApiErrorCodeEnum 等，code 多为 11xx 字符串解析后的整数：
| code | 含义 | 处理建议 |
|---|---|---|
| 1101 | decrypt failed（未预期解密/原生库异常） | 查看服务日志与 LechangeEncryptUtil 堆栈；核对密钥、imgUrl、TCM 分支 |
| 1102 | listDeviceDetailsByIds 空 body | 检查 OpenAPI 域名、签名、appId/sk |
| 1103 | 缺少 result | 对照 OpenAPI 响应结构 |
| 1104 | listDeviceDetailsByIds failed | 查看 desc 中截断的上游消息 |
| 1105 | 缺少 data | token 是否有效、是否有设备权限 |
| 1106 | 结果中无该设备 | 核对 deviceId 与 token 所属账号 |
| 1107 | 设备条目无效 | 设备状态异常或数据不完整 |
| 1108 | OpenAPI HTTP 错误 | 网络、TLS、超时（默认 3s） |
| 1109 | decode picture failed | 服务层空解密结果或未映射异常；若 body 为 2/-2 等，见 SDK 码表，勿仅查 1109 |
| 1110 | deviceAbility is empty | 无法判断 TCM，检查设备能力与 OpenAPI |
| 1111 | image download failed | imgUrl 不可达、鉴权失败、非 OSS 合法地址 |
TCM 设备：deviceAbility 含 TCM 时，secretKey 必须为 设备密码；非 TCM 时按 API 参考 — secretKey 填写序列号/自定义密钥/密码。
原生解密 SDK 码（SDKCodeEnum）
LechangeEncryptUtil / 底层库可能返回（多见于日志或内部回调）：
| code | 含义 |
|---|---|
| 0 | 解密成功 |
| -2 | url 与 deviceId 不匹配 |
| -1 | url 鉴权失败或下载失败 |
| 1 | 数据不完整 |
| 2 | 密钥错误 |
| 3 | 图片未加密 |
| 4 | 不支持的加密方式 |
| 5 | 缓冲区长度不够 |
| 99 | 未知错误 |
若 HTTP code 为 2 或 -2，按 SDK 码表处理；若为 1109 再查服务层与 OpenAPI 分支。密钥与 TCM 规则见 API 参考 — secretKey 与 码流与告警图片解密。
步骤
- 看 HTTP body 中
code/desc（非 HTTP 状态码）。 - 11xx 对照本文 OpenAPI 表；解密失败查原生 SDK 码与
secretKey、TCM 分支。 - 仍无法定位时核对 API 参考 请求字段与 token 权限。
常见问题
Q：HTTP 200 但 code 非 200
Demo 设计为业务错误仍返回 HTTP 200，请以 body 中 code / desc 为准。
Q：本地 Windows 编译成功，Linux 上解密失败
确认部署架构为 linux x86_64，并使用包内原生库；勿混用其他 SDK 版本的 so。
Q：OpenAPI 正常但解密失败
单独验证 imgUrl 在服务器上是否可下载；告警链接有时带时效或需 Referer。
Q：与 App 内 decryptPic 结果不一致
确认同一 deviceId、同一密钥策略；平台端必须走 /decodePic 且 token 对设备有权限。
Q：预览报 1001（轻应用）
属于播放器 code 问题，见 排障：预览失败，与本组件无关。