SDKs
客户端 SDK 错误码
识别 OpenIMClientSDK 通用错误码、区分错误来源，并按网络、登录、消息和群组场景处理。
适用范围
本页汇总 OpenIMClientSDK 的通用客户端错误码。iOS、Android、Flutter、WASM、Electron 等客户端虽然通过不同语言的失败回调、异常或 Promise 暴露错误，但由 OpenIM SDK Core 返回的错误码语义保持一致。平台封装层、操作系统或运行时仍可能补充本页未列出的错误，处理时应同时保留错误信息和客户端 SDK 版本。
客户端调用还可能直接返回 OpenIMServer 的业务错误。此时不要只按客户端错误码表判断，应结合错误码来源处理。
判断错误来源
| 错误码 | 来源 | 处理方式 |
|---|---|---|
0 | 通用成功码 | 表示业务处理成功，继续读取当前 API 的返回数据。 |
1~9999 | OpenIMServer | 按服务端 Platform API 错误码排查参数、权限、Token、群组或消息状态。 |
本页列出的 10000~10401 | OpenIMClientSDK | 按客户端网络、生命周期、本地数据和操作条件排查。错误码并不连续，不要根据范围推断未定义值。 |
20001~29999 | 业务服务端或 Webhook | 由接入方业务系统定义，应在业务后端维护含义和用户提示。 |
通用与登录状态
| 错误码 | 含义 | 处理建议 |
|---|---|---|
10000 | 网络请求失败 | 检查设备网络、API 地址、WebSocket 地址、TLS 证书和代理配置。网络恢复后再重试。 |
10001 | 网络请求超时 | 检查网络质量和服务状态。对于会改变状态的操作，先查询实际结果，再决定是否重试。 |
10002 | 参数无效 | 对照当前 API 页面检查必填字段、数据类型、枚举值和互斥参数。 |
10003 | 调用上下文已超时或取消 | 检查调用方超时设置、页面或任务生命周期，以及登录状态是否在调用期间发生变化。 |
10004 | 资源初始化尚未完成 | 该错误可能出现在仍使用此定义的客户端版本中。等待 SDK 初始化和登录完成后再调用依赖本地资源的 API。 |
10005 | 未识别的错误 | 保留错误信息、SDK 版本和触发 API；确认可复现步骤后再升级或提交诊断信息。 |
10006 | SDK 内部错误 | 收集客户端日志和最小复现步骤，检查 SDK 版本兼容性；不要把内部错误信息直接展示给最终用户。 |
10007 | 没有可应用的更新 | 当前同步或更新操作没有产生新数据。通常可继续使用现有状态，并按具体 API 的结果决定是否刷新。 |
10008 | SDK 尚未初始化 | 先完成当前平台的 SDK 初始化流程，并等待初始化成功后再调用其他 API。 |
10009 | SDK 尚未完成登录 | 等待登录成功事件或回调后再调用登录态 API，避免并发或重复发起登录。 |
10100 | 用户 ID 不存在或尚未注册 | 确认用户已由可信业务后端注册到 OpenIMServer，并检查客户端使用的 userID。 |
10101 | 用户已经退出登录 | 停止调用登录态 API，清理当前会话状态；需要继续使用时重新获取 Token 并登录。 |
10102 | 重复登录 | 不要在前一次登录尚未结束时再次登录。复用当前 SDK 实例，或先完成退出再切换账号。 |
消息相关错误
| 错误码 | 含义 | 处理建议 |
|---|---|---|
10200 | 文件不存在 | 检查本地文件路径、临时文件有效期和读取权限，再重新创建或上传文件消息。 |
10201 | 消息解压失败 | 检查客户端与服务端版本兼容性并重新同步消息；持续出现时保留日志排查消息数据。 |
10202 | WebSocket 二进制消息解码失败 | 检查客户端与服务端协议版本是否匹配，并排查代理是否修改了 WebSocket 数据。 |
10203 | 不支持的消息或二进制协议类型 | 使用当前 SDK 支持的消息类型，并确认客户端与服务端版本兼容。 |
10204 | 当前消息不允许重复发送 | 只有发送失败的原消息可以重发；发送成功的消息如需再次发送，应重新创建消息对象。 |
10205 | 不支持的消息内容类型 | 改用已支持的消息类型，或在客户端和服务端都完成对应自定义消息的兼容处理。 |
10206 | 消息没有服务端序列号 | 该消息尚未具备依赖 seq 的操作条件。等待发送或同步完成，并以最新消息对象重试。 |
10207 | 消息已经删除 | 从界面和本地业务状态移除该消息，不要继续对旧消息对象执行修改、撤回或查询操作。 |
会话与群组错误
| 错误码 | 含义 | 处理建议 |
|---|---|---|
10301 | 当前会话或群类型不支持该操作 | 检查 API 的适用会话和群类型，不要对不支持的群组执行该操作。 |
10302 | 当前操作只支持指定群类型 | 确认目标群的 groupType，并改用与该群类型匹配的 API。 |
10303 | 当前未读数已经为 0 | 以最新会话状态刷新界面，不要继续递减或重复清理未读数。 |
10400 | 群组 ID 不存在 | 检查 groupID，重新查询群资料，并确认群组尚未解散。 |
10401 | 群组类型无效 | 使用当前 SDK 和 OpenIMServer 支持的群类型，并检查创建或查询结果中的 groupType。 |
版本兼容
错误码定义会随客户端 SDK 版本演进。10004 存在于部分已发布版本中；当前 OpenIM SDK Core 已将初始化与登录准备状态进一步区分为 10008 和 10009。维护兼容旧版本的应用时可以继续识别 10004，新逻辑应优先分别处理未初始化和未登录状态。
不要把未出现在本页的整数自动归类为某个客户端错误。遇到未知错误时，应先确认错误来自客户端、OpenIMServer 还是业务 Webhook，再结合当前 SDK 版本的错误信息和发布说明处理。
处理建议
- 先记录错误码、错误信息、调用的 API、客户端 SDK 版本和必要的业务目标标识；Token、完整消息内容等敏感信息必须脱敏。
- 参数、登录状态和不支持的操作应先修正调用条件，不要自动重试。
- 网络失败和超时可以采用退避重试；发送消息或其他状态变更操作重试前，应先查询或同步实际状态，避免重复执行。
- 将技术错误映射为稳定的产品提示，不要直接把内部错误信息展示给最终用户。
10005、10006或解码类错误持续出现时，保留完整日志并使用对应平台的WASM 日志、iOS 日志、Flutter 日志或 Electron 日志上传说明进行诊断。
本页根据旧版客户端错误码说明迁移，并与 OpenIM SDK Core 当前错误码定义及兼容版本定义核对。
这个页面有帮助吗？