错误码

本页说明 SDK Open 业务协议使用的稳定错误码，适用于 Command WebSocket 响应、Command/Video 事件以及各业务方法返回的状态。

接入方应优先依据 code 做稳定判定；message 仅用于日志和排障，不应作为唯一分支条件。

响应结构

Command WebSocket 响应使用统一结构：

json

{
  "request_id": "req-001",
  "id": "req-001",
  "code": 0,
  "message": "ok",
  "data": {},
  "ts": 1710000000
}

字段	说明
`request_id`	对应请求中的 `request_id`。
`id`	兼容字段，当前与 `request_id` 一致。
`code`	稳定错误码，`0` 表示成功。
`message`	简短错误说明，用于日志和诊断。
`data`	响应数据或错误扩展信息。
`ts`	服务端 Unix 时间戳，单位为秒。

事件结构

Command/Video 事件使用统一结构：

json

{
  "event": "capture.completed",
  "code": 0,
  "message": "ok",
  "payload": {},
  "ts": 1710000000
}

字段	说明
`event`	事件名称。
`code`	事件状态码，`0` 表示成功。
`message`	简短状态说明，用于日志和诊断。
`payload`	事件业务数据。
`ts`	服务端 Unix 时间戳，单位为秒。

错误码分组

范围	类别	说明
`0`	成功	请求或事件处理成功。
`1000-1099`	请求协议错误	请求结构、方法名、参数或限流错误。
`1100-1199`	认证与授权错误	token、session、capability、设备授权范围或授权场景错误。
`1200-1299`	设备错误	设备发现、打开、占用、型号支持或断开错误。
`1300-1399`	视频与采集错误	视频流、预览分辨率、采集失败或采集超时错误。
`1700-1799`	SANE 错误	SANE 运行环境、设备、选项、扫描或配置档错误。
`1900-1999`	运行时与 Provider 错误	SDK 运行时内部错误或 provider 装配、调用错误。

SDK Open 状态码

code	名称	说明	处理建议
`0`	`OK`	成功。	读取 `data`。
`1000`	`INVALID_REQUEST`	请求不是合法 JSON 对象。	检查 Command WS envelope。
`1001`	`INVALID_METHOD`	`method` 缺失或非法。	使用公开方法名。
`1002`	`INVALID_PARAMS`	参数缺失或类型不满足要求。	对照开发参考补齐参数。
`1003`	`UNSUPPORTED_METHOD`	方法或格式不支持。	调用 `system.capabilities` 确认能力。
`1004`	`RATE_LIMITED`	触发限流。	降低请求频率。
`1100`	`AUTH_REQUIRED`	当前连接未创建 session。	先调用 `auth.create_session`。
`1101`	`TOKEN_INVALID`	API Key 无效。	检查 Key 明文、状态和授权模式。
`1102`	`TOKEN_EXPIRED`	API Key 或 token 过期。	轮换或重新签发。
`1103`	`SESSION_TOKEN_INVALID`	session token 无效。	重新创建 session。
`1104`	`ACCOUNT_TYPE_NOT_ALLOWED`	权益等级不允许。	升级 Key tier 或检查 capability。
`1105`	`DEVICE_NOT_IN_AUTH_SCOPE`	设备不在授权范围。	调整 API Key 的 `deviceScope`。
`1106`	`AUTH_SCENE_MISMATCH`	当前授权场景不满足 SDK 要求。	检查授权场景配置并重新签发授权。
`1107`	`CAPABILITY_NOT_ALLOWED`	当前 session 没有目标方法权限，或请求的参数级能力超过当前权益等级；例如 VIP/SVIP/SVIP+ 能力未授权、在线 API Key 尚未完成商务授权且请求能力超过购买等级。	检查 `auth_context.capabilities`、`auth_context.account_type`、`auth_context.licensed_account_type` 和接口参数对应的权益等级；升级 Key tier 或完成商务授权后重试。
`1108`	`OFFLINE_AUTH_CODE_INVALID`	离线授权码无效。	重新生成匹配机器码的授权码。
`1109`	`ONLINE_AUTH_UNAVAILABLE`	在线授权不可用。	检查网关地址和网络。
`1110`	`USAGE_LIMIT_EXCEEDED`	额度不足；trial 状态调用 VIP/SVIP/SVIP+ 受限能力且共享试用额度已用完时也会返回该错误，例如 message 为 `trial quota exhausted`。	等待额度恢复、升级 tier、完成离线激活或在线商务授权；trial 试用额度耗尽后不要重试同一受限能力。
`1111`	`OFFLINE_BINDING_MISMATCH`	离线授权和机器不匹配。	使用当前机器码重新生成授权码。
`1200`	`DEVICE_NOT_FOUND`	设备不存在。	检查连接和设备 ID。
`1201`	`DEVICE_BUSY`	设备忙。	停止视频或关闭设备后重试。
`1202`	`DEVICE_OPEN_FAILED`	打开设备失败。	检查驱动、权限和 provider。
`1203`	`DEVICE_NOT_OPEN`	设备未打开。	先调用 `device.open`。
`1204`	`DEVICE_MODEL_UNSUPPORTED`	设备型号不支持。	检查设备能力。
`1205`	`DEVICE_DISCONNECTED`	设备断开。	重新连接设备。
`1300`	`STREAM_NOT_FOUND` / `STREAM_NOT_READY`	stream 不存在或未就绪；当前两个名称共用同一个数值。	重新调用 `video.start`，并等待视频流就绪。
`1301`	`CAPTURE_FAILED`	拍摄失败。	检查设备状态和 profile。
`1302`	`PREVIEW_RESOLUTION_UNSUPPORTED`	预览分辨率不支持。	使用 `device.get` 返回的分辨率。
`1303`	`CAPTURE_TIMEOUT`	拍摄超时。	增加 `timeout_ms` 或检查设备。
`1700`	`SANE_NOT_AVAILABLE`	SANE 不可用。	仅 Linux 支持，检查 provider 和 SANE 运行库。
`1701`	`SANE_DEVICE_NOT_FOUND`	SANE 设备不存在。	调用 `sane.list` 刷新。
`1702`	`SANE_DEVICE_BUSY`	SANE 设备忙。	关闭旧 session 后重试。
`1703`	`SANE_OPTION_INVALID`	SANE option 无效。	对照 `sane.get_options` 的约束设置。
`1704`	`SANE_SCAN_FAILED`	SANE 扫描失败。	检查设备、纸张和驱动日志。
`1705`	`SANE_PROFILE_NOT_FOUND`	配置档不存在。	刷新 profile 列表。
`1900`	`INTERNAL_ERROR`	内部错误。	查看 runtime 日志。
`1901`	`PROVIDER_NOT_READY`	provider 未就绪。	检查 runtime 启动和 provider 装配。
`1902`	`PROVIDER_CALL_FAILED`	provider 调用失败。	查看 provider 错误和日志。

错误码 ​

响应结构 ​

事件结构 ​

错误码分组 ​

SDK Open 状态码 ​

错误码

响应结构

事件结构

错误码分组

SDK Open 状态码