错误码与故障排查

iKho Embedded 平台接口的统一错误响应结构、HTTP 状态语义、按 API 分组的错误码,以及带 request_id 的排查流程。

统一错误响应结构

平台接口出错时,响应体为统一的 JSON 结构:code 是机器可读的错误码,message 是面向开发者的中文说明,request_id 是本次请求的唯一标识。程序里请只依赖 code 做分支判断,不要匹配 message 文案;request_id 用于联系支持时定位日志。

{
  "code": "IKHO_ERR_TOKEN_EXPIRED",
  "message": "访问令牌已过期,请重新获取。",
  "request_id": "req_9f3c1a2b7d"
}

HTTP 状态语义

HTTP 状态码给出错误的大类,响应体里的 code 给出具体原因。两者配合定位问题。

认证 API 错误码

见认证 API 总览。多数认证错误可以在你的后端自动恢复:令牌过期重签即可,不要把 secret 下发到端上重试。

文件上传 API 错误码

见文件上传 API 总览。分片上传的常见失败点在合并这一步:分片没传全、ETag 没存对,合并就会失败。

转写 API 错误码

见转写 API 总览。注意区分两类失败:提交或查询接口直接报错(本表),与任务进入 FAILURE 终态(任务受理成功但处理失败,原因在任务详情里返回)。

SDK 端错误与 API 错误的对应关系

Embedded SDK 的错误码(IKhoError)与本页的平台错误码是同一套 IKHO_ERR_* 命名下的两层:设备侧错误(如 IKHO_ERR_BLE_UNAVAILABLE、IKHO_ERR_BIND_OCCUPIED、IKHO_ERR_WIFI_HANDSHAKE)发生在手机与 S1 之间,只会出现在 SDK 回调里,不会出现在 REST 响应中;而 SDK 内部调用平台接口失败时,会把平台错误映射为 SDK 错误抛出,并在错误对象里保留底层的 code 与 request_id。最常见的一条对应是:平台返回 401(IKHO_ERR_TOKEN_INVALID 或 IKHO_ERR_TOKEN_EXPIRED)时,SDK 侧统一表现为 IKHO_ERR_UNAUTHORIZED,处理方式都是由你的后端重签用户令牌后调用 setUserToken。排查 SDK 报错时,先看错误对象里有没有 request_id:有,说明问题出在平台接口,按本页错误码处理;没有,说明问题出在设备连接,按 iOS SDK 的错误码表处理。

排查流程

自查无法解决时,按下面三步整理信息再联系支持,能明显缩短定位时间。

常见故障速查

下一步