# 错误码与故障排查

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

本页错误码为内测契约,以联调时提供的正式文档为准。SDK 层错误码(设备扫描、绑定、同步)见 [iOS SDK](/docs/embedded/ios-sdk/) 的「错误码」一节。

## 统一错误响应结构

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

  错误响应示例(内测契约,以联调为准)
    
  

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

## HTTP 状态语义

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

| 状态码 | 语义 | 典型场景 |
|---|---|---|
| `400` | 请求参数错误 | 缺少必填字段、字段格式不合法、取值超出允许范围 |
| `401` | 未认证 | 凭证缺失、令牌无效或已过期 |
| `403` | 已认证但无权限 | 令牌级别与接口不匹配、内测账号被停用、额度受限 |
| `404` | 资源不存在 | 转写任务、上传会话或文件标识找不到 |
| `409` | 状态冲突 | 分片缺失、校验值不一致、重复提交合并 |
| `413` | 请求体或文件超限 | 文件大小或音频时长超出上限(内测期以联调口径为准) |
| `429` | 请求频率超限 | 轮询过密或并发过高触发限流(内测期以联调口径为准) |
| `5xx` | 服务端错误 | 平台内部异常,可按指数退避重试;持续出现请携 `request_id` 联系支持 |

## 认证 API 错误码

见[认证 API 总览](/docs/api-reference/auth/overview/)。多数认证错误可以在你的后端自动恢复:令牌过期重签即可,不要把 `secret` 下发到端上重试。

| 错误码 | 状态码 | 含义 | 建议处理 |
|---|---|---|---|
| `IKHO_ERR_INVALID_CLIENT` | 401 | `client_id` 或 `secret` 不正确 | 核对开通邮件里的凭证;确认 Basic 值为 `base64(client_id:secret)` 且不含换行 |
| `IKHO_ERR_TOKEN_INVALID` | 401 | 令牌格式错误或签名校验失败 | 确认传入的是完整令牌且未被截断,`Bearer` 与令牌之间只有一个空格 |
| `IKHO_ERR_TOKEN_EXPIRED` | 401 | 访问令牌已过期 | 合作方令牌用 `refresh_token` 续期;用户令牌由后端重签后调用 `setUserToken` 下发 |
| `IKHO_ERR_REFRESH_EXPIRED` | 401 | `refresh_token` 已过期或已被使用 | 用 `client_id` 与 `secret` 重新走一遍获取合作方令牌流程 |
| `IKHO_ERR_USER_ID_INVALID` | 400 | `user_id` 不符合 6 到 120 个字符的要求 | 用你系统里对该用户的稳定标识,并校验长度 |
| `IKHO_ERR_SCOPE_DENIED` | 403 | 令牌级别与接口不匹配 | 签发用户令牌要用合作方令牌;绑定设备与上传文件要用用户令牌,不要混用 |
| `IKHO_ERR_ACCOUNT_DISABLED` | 403 | 内测账号已被停用 | 携 `request_id` 与对接工程师确认账号状态 |

## 文件上传 API 错误码

见[文件上传 API 总览](/docs/api-reference/file/overview/)。分片上传的常见失败点在合并这一步:分片没传全、`ETag` 没存对,合并就会失败。

| 错误码 | 状态码 | 含义 | 建议处理 |
|---|---|---|---|
| `IKHO_ERR_FILETYPE_UNSUPPORTED` | 400 | `filetype` 不在支持范围 | 只支持 `mp3`、`m4a`、`wav`,转换格式后重新上传 |
| `IKHO_ERR_FILE_TOO_LARGE` | 413 | 文件大小超出单文件上限 | 上限内测期以联调口径为准;超限文件请切分录音或压缩码率后重试 |
| `IKHO_ERR_UPLOAD_ID_EXPIRED` | 404 | `upload_id` 失效或上传会话已过期 | 重新调用生成预签名地址,开启新的上传会话并重传全部分片 |
| `IKHO_ERR_PART_MISSING` | 409 | 分片缺失,`part_list` 与实际已上传分片不一致 | 核对每个分片的 `PUT` 是否成功,补传缺失分片后再合并 |
| `IKHO_ERR_ETAG_MISMATCH` | 409 | 某个分片的 `ETag` 校验失败 | 用 `PUT` 响应头里原样返回的 `ETag`,不要去掉引号或改写大小写;必要时重传该分片 |
| `IKHO_ERR_MD5_MISMATCH` | 409 | `file_md5` 与合并后文件不一致 | 确认 MD5 按整个文件计算且为十六进制;或先不传 `file_md5` 定位问题 |

## 转写 API 错误码

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

| 错误码 | 状态码 | 含义 | 建议处理 |
|---|---|---|---|
| `IKHO_ERR_FILE_URL_UNREACHABLE` | 400 | `file_url` 无法访问 | 预签名下载地址有效期约 24 小时,过期后重新走合并流程换取新地址;自有地址需可公网访问 |
| `IKHO_ERR_AUDIO_UNDECODABLE` | 400 | 音频无法解码 | 确认文件是完整的 `mp3`、`m4a` 或 `wav`,扩展名与实际编码一致 |
| `IKHO_ERR_DURATION_EXCEEDED` | 413 | 音频时长超出单任务上限 | 上限内测期以联调口径为准;超长录音切分后分多个任务提交 |
| `IKHO_ERR_MODEL_INVALID` | 400 | `model` 取值不合法 | 只支持 `ikho-asr-pro` 与 `ikho-asr-fast` |
| `IKHO_ERR_TASK_NOT_FOUND` | 404 | `transcription_id` 对应的任务不存在 | 核对任务标识是否完整,以及查询用的 `client_id` 与提交时是否一致 |
| `IKHO_ERR_QUOTA_EXCEEDED` | 403 | 转写时长额度已用尽 | 免费额度为 300 小时转写;超出部分按量付费,单价以商务合同为准,请联系对接工程师开通 |
| `IKHO_ERR_RATE_LIMITED` | 429 | 请求频率超限 | 拉长轮询间隔并加指数退避;限流阈值内测期以联调口径为准 |

## 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](/docs/embedded/ios-sdk/) 的错误码表处理。

## 排查流程

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

  
    1

    拿到 request_id
从错误响应体或 SDK 错误对象里取出 `request_id`。没有 `request_id` 的设备侧错误,改为记录设备序列号与复现步骤。

  

  
    2

    记录时间点与 client_id 前 6 位
记下报错发生的时间(精确到分钟)与你的 `client_id` 前 6 位。不要在任何渠道发送完整的 `secret` 或 `api_key`。

  

  
    3

    联系支持
把 `request_id`、时间点、`client_id` 前 6 位与错误码一并发给对接工程师,见[联系我们](/docs/mcp-cli/contact/)。

  

## 常见故障速查

| 症状 | 常见原因 | 处置 |
|---|---|---|
| 获取合作方令牌一直 401 | Basic 值拼装错误,`base64(client_id:secret)` 里混入了换行或空格 | 重新编码并确认冒号分隔、无换行;核对凭证来自开通邮件 |
| 用户令牌每天固定时间失效 | 用户令牌有效期约 24 小时,后端没有在过期前重签 | 后端提前重签,SDK 侧调用 `setUserToken` 更新,无需重新配置 |
| 分片 `PUT` 返回 403 | 预签名地址已过期,或把分片传到了错误序号的地址 | 重新生成预签名地址;按 `PartNumber` 与地址一一对应上传 |
| 合并分片返回 409 | 有分片未成功上传,或 `ETag` 没有按响应头原样保存 | 核对 `part_list` 的数量与 `ETag`,补传缺失分片后重新合并 |
| 提交转写报 `file_url` 不可达 | `DownloadUrl` 已超过约 24 小时有效期 | 重新走合并流程换取新地址;拿到地址后尽快提交转写 |
| 任务长时间停在 `PROGRESS` | 音频较长或队列繁忙 | 继续轮询并加大间隔;远超预期时携 `request_id` 联系支持 |
| 任务进入 `FAILURE` 但音频能正常播放 | 音频编码异常、静音占比过高或内容无有效语音 | 用标准编码重新导出 `mp3`、`m4a` 或 `wav` 后重试;仍失败携 `request_id` 联系支持 |
| 频繁收到 429 | 轮询间隔过短或并发提交过多 | 拉长轮询间隔、加指数退避、控制并发;限流阈值内测期以联调口径为准 |

## 下一步

[iOS SDK 错误码 设备扫描、绑定、同步等设备侧错误码与建议处理。 打开 iOS SDK](/docs/embedded/ios-sdk/)

[联系我们 整理好 `request_id`、时间点与错误码,交给对接工程师定位。 联系支持](/docs/mcp-cli/contact/)