错误码速查

本页汇总 iOS 与 Android 的错误模型与统一错误码表，便于快速检索。

iOS

TmkTranslationErrorCategory

public enum TmkTranslationErrorCategory: String {
    case caller
    case network
    case rtcRtm
    case audio
    case state
    case `internal`
}

TmkTranslationError

public enum TmkTranslationError: Error, LocalizedError

常用公开属性：

属性	说明
code	SDK 统一错误码。
constantName	错误码常量名。
message	对外可读错误文案。
category	错误分类。
chineseDescription / englishDescription	中英文说明。
underlyingError	原始底层错误。
actualErrorCode	实际底层错误码，例如离线组件或 LicenseCore 诊断码。
actualErrorMessage	实际底层错误信息；上传或展示前必须脱敏。
actualErrorDomain	实际底层错误域。

示例：

func onError(_ error: TmkTranslationError) {
    print(error.code)
    print(error.category.rawValue)
    print(error.message)
    let safeActualMessage = error.actualErrorMessage == nil ? "-" : "<redacted>"
    print(safeActualMessage)
}

统一错误码表

以下表格合并 SDK 统一错误码、离线组件诊断码和离线 License 鉴权组件码。业务 UI 主要消费 error.code；actualErrorCode / actualErrorMessage 只用于脱敏后的诊断排障。

code	constantName	适用范围/分类	说明	处理契约
2001101	SDK_NOT_INITIALIZED	common/state	SDK 未初始化。	提示初始化失败，先完成 sdkInit，不要继续建房或建通道。
2001102	AUTHENTICATION_FAILED	common/caller	在线鉴权失败，或离线能力接口/离线通道因 License 鉴权失败而无法继续。	在线鉴权失败时提示重新鉴权；离线能力失败时引导联网重试或检查账号权限。
2001103	ROOM_CREATION_FAILED	online/network	在线房间创建失败。	允许用户重试创建；连续失败时离开当前对话并记录诊断。
2001104	CHANNEL_CREATION_FAILED	common/rtcRtm	在线通道创建失败，或离线通道组装失败。	在线重新创建对话；离线重新初始化通道并检查模型资源。
2001105	ENGINE_NOT_SUPPORTED	common/rtcRtm	当前 SDK、账号或配置不支持该引擎能力。	提示能力不支持，停止当前流程。
2001106	INVALID_CONFIGURATION	common/caller	配置非法，包括语言、声道、音色、appId、channel 等参数不合法。	修正配置后再创建；不要用旧配置重复重试。
2001107	NETWORK_UNAVAILABLE	common/network	网络不可用；也可能出现在模型下载、鉴权、语言列表等网络请求失败场景。	reconnecting 时提示恢复中；下载或请求失败时提供重试入口。
2001108	AUDIO_PROCESSING_ERROR	common/audio	采集、播放、推 PCM 或音频会话异常。	停止录音/播放，在线重建对话，离线重新初始化。
2001109	TTS_SYNTHESIS_ERROR	common/rtcRtm	在线或离线 TTS 合成异常；离线 stage == tts 优先映射到该错误。	单句失败可弱提示；连续失败或通道失败时重建/重新初始化。
2001110	TRANSLATION_ERROR	common/rtcRtm	在线翻译异常；离线 ASR/MT 阶段失败。	单句失败可弱提示；通道失败时在线重建，离线重新初始化。
2001111	SESSION_EXPIRED	online/network	在线会话或 RTC/RTM token 已过期。	停止当前会话，提示用户重新创建对话。
2001112	QUOTA_EXCEEDED	common/network	账号或应用服务配额不足。	提示配额不足并停止当前流程。
2001113	INVALID_LANGUAGE_CODE	common/caller	语言代码非法或当前模式不支持；离线会归一 zh-CN、zh-HK 等到 zh，当前离线主要支持 zh / en。	引导重新选择支持语言；在线重新创建对话，离线重新初始化通道。
2001114	ENGINE_INITIALIZATION_FAILED	common/rtcRtm	引擎初始化失败；离线 creation failed、load timeout 或模型加载超时。	允许重试；多次失败时提示检查 SDK 资源和离线模型完整性。
2001115	BUFFER_OVERFLOW	common/audio	音频输入或输出缓冲超过处理能力。	降低推流频率或重启采集；严重时重建通道。
2001116	THREAD_INTERRUPTED	common/internal	工作线程被中断。	允许重试；若持续出现，记录诊断并重建流程。
2001117	OFFLINE_MODEL_NOT_READY	offline/model	模型缺失、校验失败、下载失败、离线鉴权未通过或账号未开通离线能力。	引导下载、更新模型或重新鉴权；不要直接启动离线通道。
2001999	UNKNOWN_ERROR	common/internal	未知错误或底层错误无法映射。	记录诊断，在线重建对话，离线重新初始化。
2002001	NETWORK_INVALID_URL	common/caller	网络 URL、模型下载 URL 或后台地址配置错误。	提示配置错误，停止当前流程。
2002002	NETWORK_TRANSPORT_ERROR	common/network	网络传输失败，包括 DNS、TLS、超时或模型下载失败。	提供重试；模型下载场景保留续传/重试入口。
2002003	NETWORK_HTTP_STATUS_ERROR	common/network	HTTP 非成功状态。	401/403 优先重新鉴权，5xx 可重试，其他状态按服务端文案处理。
2002004	NETWORK_RESPONSE_DECODING_ERROR	common/network	响应、manifest 或语言列表解析失败。	提示服务响应异常，记录诊断。
2002005	NETWORK_BUSINESS_ERROR	common/network	服务端业务错误。	展示服务端错误文案；必要时重新鉴权或离开当前流程。
2002006	REQUEST_CANCELLED	common/network	用户取消、页面退出、主动停止或音色设置被取消。	不弹错误框，仅恢复 UI 到已取消/已停止状态。
2003002	INVALID_STATE	common/state	当前状态不允许操作；例如通道释放后继续调用。	重复停止可忽略；关键路径失败时重建或重新初始化。
2003003	DEPENDENCY_UNAVAILABLE	common/rtcRtm	必要依赖、离线库或模型能力不可用。	提示 SDK/资源异常，停止当前流程并记录诊断。
2003004	RTC_OPERATION_FAILED	online/rtcRtm	实时链路操作失败，包括 RTC/RTM 启动失败、发消息失败、服务端订阅 uid 离线或底层 RTC 错误。	提示重新创建或离开；online_remote_user_offline 且 is_expected_service_uid=true 时当前对话不可继续。
2003005	MESSAGE_DECODING_FAILED	common/rtcRtm	在线/离线消息解析失败。	仅记录日志，不直接关闭通道。
2003006	AUDIO_CHANNEL_CREATION_FAILED	common/audio	音频通道创建失败。	停止采集并提示重建/重新初始化。
2003007	TRACK_EVENT_NOT_CONFIGURED	common/internal	埋点未配置。	不影响翻译主流程，可忽略或记录日志。
2003008	TRACK_EVENT_INVALID_EVENT_NAME	common/caller	埋点事件名为空或非法。	不影响翻译主流程，可忽略或修正埋点配置。
2004001	OFFLINE_INVALID_ARGUMENT	offline/diagnostic	离线翻译组件参数无效。	作为 actualErrorCode 排障；修正语言、声道、模型路径或开关配置后重新初始化。
2004002	OFFLINE_CREATION_FAILED	offline/diagnostic	离线引擎创建失败。	作为 actualErrorCode 排障；检查模型文件和依赖资源，重新初始化离线通道。
2004003	OFFLINE_OPERATION_FAILED	offline/diagnostic	离线引擎操作失败。	作为 actualErrorCode 排障；停止当前 pipeline 后重新初始化。
2004004	OFFLINE_ENGINE_RELEASED	offline/diagnostic	离线引擎已释放后继续调用。	作为 actualErrorCode 排障；忽略退出后的回调或重新创建通道。
2004005	OFFLINE_LOAD_TIMEOUT	offline/diagnostic	离线模型加载超时。	作为 actualErrorCode 排障；检查模型完整性并重新加载。
2004101	OFFLINE_AUTH_EMPTY_CONTENT	offline/license	License 内容为空；native 返回码 1001。	重新联网鉴权并获取 License；不要继续启动离线通道。
2004102	OFFLINE_AUTH_DECRYPT_OR_PARSE_FAILED	offline/license	License 解密或解析失败；native 返回码 1002。	重新联网鉴权；不要删除设备密钥，不上传原始 License。
2004103	OFFLINE_AUTH_SIGNATURE_INVALID	offline/license	License 签名无效；native 返回码 1003。	重新联网鉴权；若仍失败，检查后台签发配置。
2004104	OFFLINE_AUTH_CLIENT_PACKAGE_OR_DEVICE_MISMATCH	offline/license	client、包名或设备绑定不匹配；native 返回码 1004。	检查包名、账号和设备绑定，重新鉴权。
2004105	OFFLINE_AUTH_MODEL_KEY_EMPTY	offline/license	模型密钥为空；native 返回码 1005。	检查账号离线授权范围，重新鉴权。
2004106	OFFLINE_AUTH_EXPIRED_OR_NOT_YET_VALID	offline/license	License 已过期或尚未生效；native 返回码 1006。	联网重新签发 License 后再使用离线能力。
2004107	OFFLINE_AUTH_UNSUPPORTED	offline/license	License 版本或算法不支持；native 返回码 1007。	升级 SDK 或联系后台确认签发格式。
2004108	OFFLINE_AUTH_UNAUTHORIZED_SCOPE_OR_MODEL	offline/license	当前 scope 或模型未授权；native 返回码 1008。	检查账号授权范围，重新鉴权或联系后台开通。
2004199	OFFLINE_AUTH_INTERNAL_ERROR	offline/license	离线 License 鉴权内部错误或未知 native 返回码。	记录诊断，联网重试；持续失败时提交脱敏日志排查。

补充说明：

• 离线翻译在底层失败时，会按阶段映射为统一错误码：tts → 2001109 / TTS_SYNTHESIS_ERROR，translation/asr → 2001110 / TRANSLATION_ERROR。底层组件码保留在 actualErrorCode 中。

• 离线 License 鉴权失败不会导致在线 verifyAuth(_:) 回调失败；当业务继续调用离线能力接口或创建离线通道时，对外 error.code 统一映射为 2001102 / AUTHENTICATION_FAILED，offlineLib 组件码写入 error.actualErrorCode，native LicenseCore 返回码写入 error.actualErrorMessage。

凭据安全

License 签发响应可能返回 license_id 或 licenseId。SDK 仅可将脱敏后的 licenseId 用于诊断关联，不应输出原始 License、clientSecret 或设备私钥。

---

Android

TmkTranslationException

Android 对外错误通常通过 TmkTranslationException 或错误码返回：

class TmkTranslationException : Exception {
    // 对外统一错误码（2001xxx/2002xxx/2003xxx，见下表）。
    val errorCode: Int
    // 底层原始错误码（后台业务码、HTTP 状态码或 native 返回码等）；无原始码时为 null。
    val actualErrorCode: Int?
    // 底层原始错误信息；无原始信息时为 null。
    val actualErrorMessage: String?
    // 底层原始错误域，用于区分原始码来源，如 "backend"、"OfflineLicenseApplyStatus"；无时为 null。
    val actualErrorDomain: String?
}

错误码规则：凡来自后台或底层（native）的原始错误，errorCode 始终是上表中的统一 SDK 错误码，原始错误码与信息保留在 actualErrorCode / actualErrorMessage / actualErrorDomain 中，便于业务侧排障而不破坏统一码契约。纯 SDK 内部错误（如未初始化、状态非法、超时）这三个字段为 null。

主要回调入口：

• AuthCallback.onError

• CreateRoomCallback.onError

• CreateChannelCallback.onError

• ActionCallback.onError

• TmkTranslationListener.onError

• TmkTranslationChannelStateSnapshot.code

统一错误码表

以下表格合并 SDK 统一错误码、Android 离线引擎诊断码和离线 License 鉴权组件码。业务 UI 主要消费回调中的顶层错误码；离线引擎和 License 组件码用于脱敏后的诊断排障。

code	constantName	适用范围/分类	说明	处理契约
2001101	SDK_NOT_INITIALIZED	common/state	SDK 未初始化。	提示初始化失败，先完成 sdkInit，不要继续建房或建通道。
2001102	AUTHENTICATION_FAILED	common/caller	在线鉴权失败，或离线 License 鉴权失败导致离线能力无法确认。	提示重新鉴权；离线能力失败时引导联网重试或检查账号权限。
2001103	ROOM_CREATION_FAILED	online/network	在线房间创建失败。	允许用户重试创建；连续失败时离开当前对话并记录诊断。
2001104	CHANNEL_CREATION_FAILED	common/rtcRtm	在线通道创建失败，或离线通道组装失败。	在线重新创建对话；离线重新初始化通道并检查模型资源。
2001105	ENGINE_NOT_SUPPORTED	common/rtcRtm	当前 SDK、账号或配置不支持该引擎能力。	提示能力不支持，停止当前流程。
2001106	INVALID_CONFIGURATION	common/caller	配置非法，包括语言、声道、音色、appId、channel 等参数不合法。	修正配置后再创建；不要用旧配置重复重试。
2001107	NETWORK_UNAVAILABLE	common/network	网络不可用；也可能出现在模型下载、鉴权、语言列表等网络请求失败场景。	reconnecting 时提示恢复中；下载或请求失败时提供重试入口。
2001108	AUDIO_PROCESSING_ERROR	common/audio	采集、播放、推 PCM 或音频会话异常。	停止录音/播放，在线重建对话，离线重新初始化。
2001109	TTS_SYNTHESIS_ERROR	common/rtcRtm	在线或离线 TTS 合成异常；离线 stage == tts 优先映射到该错误。	单句失败可弱提示；连续失败或通道失败时重建/重新初始化。
2001110	TRANSLATION_ERROR	common/rtcRtm	在线翻译异常；离线 ASR/MT 阶段失败。	单句失败可弱提示；通道失败时在线重建，离线重新初始化。
2001111	SESSION_EXPIRED	online/network	在线会话或 RTC/RTM token 已过期。	停止当前会话，提示用户重新创建对话。
2001112	QUOTA_EXCEEDED	common/network	账号或应用服务配额不足。	提示配额不足并停止当前流程。
2001113	INVALID_LANGUAGE_CODE	common/caller	语言代码非法或底层引擎拒绝当前 locale。离线 SDK 不做语种白名单拦截，归一 zh-CN、zh-HK 等到 zh 后按 License scope 与模型资源放行；此码现仅在底层引擎运行期判定 locale 非法时产生。	引导重新选择支持语言；在线重新创建对话，离线确认对应语种模型已下载后重新初始化通道。
2001114	ENGINE_INITIALIZATION_FAILED	common/rtcRtm	引擎初始化失败；离线 creation failed、load timeout 或模型加载超时。	允许重试；多次失败时提示检查 SDK 资源和离线模型完整性。
2001115	BUFFER_OVERFLOW	common/audio	音频输入或输出缓冲超过处理能力。	降低推流频率或重启采集；严重时重建通道。
2001116	THREAD_INTERRUPTED	common/internal	工作线程被中断。	允许重试；若持续出现，记录诊断并重建流程。
2001117	OFFLINE_MODEL_NOT_READY	offline/model	模型缺失、校验失败、下载失败、离线鉴权未通过或账号未开通离线能力。	引导下载、更新模型或重新鉴权；不要直接启动离线通道。
2001999	UNKNOWN_ERROR	common/internal	未知错误或底层错误无法映射。	记录诊断，在线重建对话，离线重新初始化。
2002001	NETWORK_INVALID_URL	common/caller	网络 URL、模型下载 URL 或后台地址配置错误。	提示配置错误，停止当前流程。
2002002	NETWORK_TRANSPORT_ERROR	common/network	网络传输失败，包括 DNS、TLS、超时或模型下载失败。	提供重试；模型下载场景保留续传/重试入口。
2002003	NETWORK_HTTP_STATUS_ERROR	common/network	HTTP 非成功状态。	401/403 优先重新鉴权，5xx 可重试，其他状态按服务端文案处理。
2002004	NETWORK_RESPONSE_DECODING_ERROR	common/network	响应、manifest 或语言列表解析失败。	提示服务响应异常，记录诊断。
2002005	NETWORK_BUSINESS_ERROR	common/network	服务端业务错误。	展示服务端错误文案；必要时重新鉴权或离开当前流程。
2002006	REQUEST_CANCELLED	common/network	用户取消、页面退出、主动停止或音色设置被取消。	不弹错误框，仅恢复 UI 到已取消/已停止状态。
2003002	INVALID_STATE	common/state	当前状态不允许操作；例如通道释放后继续调用。	重复停止可忽略；关键路径失败时重建或重新初始化。
2003003	DEPENDENCY_UNAVAILABLE	common/rtcRtm	必要依赖、离线库或模型能力不可用。	提示 SDK/资源异常，停止当前流程并记录诊断。
2003004	RTC_OPERATION_FAILED	online/rtcRtm	实时链路操作失败，包括 RTC/RTM 启动失败、发消息失败、服务端订阅 uid 离线或底层 RTC 错误。	提示重新创建或离开；online_remote_user_offline 且 is_expected_service_uid=true 时当前对话不可继续。
2003005	MESSAGE_DECODING_FAILED	common/rtcRtm	在线/离线消息解析失败。	仅记录日志，不直接关闭通道。
2003006	AUDIO_CHANNEL_CREATION_FAILED	common/audio	音频通道创建失败。	停止采集并提示重建/重新初始化。
2003007	TRACK_EVENT_NOT_CONFIGURED	common/internal	埋点未配置。	不影响翻译主流程，可忽略或记录日志。
2003008	TRACK_EVENT_INVALID_EVENT_NAME	common/caller	埋点事件名为空或非法。	不影响翻译主流程，可忽略或修正埋点配置。
2004001	ERROR_ASR_INIT_FAILED	offline/diagnostic	ASR Session 创建失败，常见于模型文件缺失。	作为底层诊断码处理；检查 ASR 模型后重新初始化离线通道。
2004002	ERROR_MT_INIT_FAILED	offline/diagnostic	MT Session 创建失败。	作为底层诊断码处理；检查 MT 模型后重新初始化离线通道。
2004003	ERROR_TTS_INIT_FAILED	offline/diagnostic	TTS Session 创建失败。	作为底层诊断码处理；检查 TTS 模型和 tmk-tts-data 后重新初始化。
2004004	ERROR_ASR_RUNTIME	offline/diagnostic	ASR 运行时错误。	弱提示或重新初始化；保留诊断日志。
2004005	ERROR_MT_RUNTIME	offline/diagnostic	MT 翻译运行时异常。	弱提示或重新初始化；保留诊断日志。
2004006	ERROR_TTS_RUNTIME	offline/diagnostic	TTS 合成运行时异常。	弱提示或重新初始化；保留诊断日志。
2004007	ERROR_MODEL_NOT_FOUND	offline/diagnostic	模型文件不存在。	引导下载或更新模型，禁止直接启动离线通道。
2004008	ERROR_MODEL_DOWNLOAD_FAILED	offline/diagnostic	模型下载失败。	恢复下载按钮，允许重试或续传。

离线 License 鉴权失败时，Android 统一回调对外错误码 2001102 / AUTHENTICATION_FAILED（TmkTranslationException.errorCode）；底层 native LicenseCore 的返回码不作为独立对外错误码，而是结构化保留在异常字段中：actualErrorCode = native 返回码（1001–1099），actualErrorMessage = OfflineLicenseApplyStatus.diagnosticSummary（如 UNAUTHORIZED_SCOPE_OR_MODEL(1008)），actualErrorDomain = "OfflineLicenseApplyStatus"，仅用于排障。该枚举（co.timekettle.offlinesdk.OfflineLicenseApplyStatus）取值如下：

OfflineLicenseApplyStatus	actualErrorCode	触发场景
EMPTY_CONTENT	1001	License 内容为空。
DECRYPT_OR_PARSE_FAILED	1002	License 解密或解析失败。
SIGNATURE_INVALID	1003	License 签名无效。
CLIENT_PACKAGE_OR_DEVICE_MISMATCH	1004	client、包名或设备绑定不匹配。
MODEL_KEY_EMPTY	1005	模型密钥为空。
EXPIRED_OR_NOT_YET_VALID	1006	License 已过期或尚未生效。
UNSUPPORTED	1007	License 版本或算法不支持。
UNAUTHORIZED_SCOPE_OR_MODEL	1008	当前 scope 或模型未授权。
INTERNAL_ERROR	1098	离线 License 鉴权内部错误。
UNKNOWN	1099	未知 native 返回码。

补充说明：

• 后台业务/RTC 命令失败（如建房、运行中切换引擎/能力/语言、音色更新）时，errorCode 为统一 SDK 码（如 ROOM_CREATION_FAILED、RTC_OPERATION_FAILED、NETWORK_BUSINESS_ERROR），后台原始码保留在 actualErrorCode、actualErrorDomain="backend"。

• 离线通道底层 ASR/MT/TTS 组件码可能被 SDK 映射为 2001109、2001110、2001114 或 2001117 后回调业务侧；组件码用于定位具体离线阶段。

• 离线 License 鉴权失败时，对外统一表现为 2001102 / AUTHENTICATION_FAILED，native 返回码见上表。诊断日志可以记录 OfflineLicenseApplyStatus 诊断枚举和 native LicenseCore 返回码，但不能上传原始 License、clientSecret 或设备私钥。

---