Web IMKit 状态码

IMKit 不产生独立错误码：组件的数据与操作最终由 IMLib 完成，错误码统一来自 errors.json。组件层负责把错误映射为可展示的 UI 状态（提示、空态、重试、禁用）。

返回信封与错误形态

层	信封	说明
客户端	`RcResult {code,data?,msg?}`	IMLib 统一返回；IMKit 读取 code / msg
WebSocket	`Frame {id?,type:'error',data:{code,message}}`	协议错误帧；SDK 转为 RcResult

UI 相关状态码

错误码	名称	分类	可重试	UI 建议
`1001`	`INVALID_PARAMETER`	客户端 / 参数 / 权限	否	参数错误：检查目标会话、消息内容与选项，提示用户重试。
`1002`	`INVALID_TOKEN`	客户端 / 参数 / 权限	否	Token 无效：跳转登录，重新获取 Token 后重连。
`1003`	`FORBIDDEN`	客户端 / 参数 / 权限	否	无权限：提示无操作权限，隐藏相应入口。
`1004`	`USER_NOT_FOUND`	客户端 / 参数 / 权限	否	用户不存在：提示用户已注销或 ID 错误。
`1005`	`GROUP_NOT_FOUND`	客户端 / 参数 / 权限	否	群组不存在：提示群已解散，刷新会话列表。
`1006`	`NOT_GROUP_MEMBER`	客户端 / 参数 / 权限	否	未加入群组：提示先加入群组。
`1007`	`MESSAGE_TOO_LARGE`	客户端 / 参数 / 权限	否	消息体过大：压缩图片/文件或截断文本。
`1008`	`RATE_LIMITED`	客户端 / 参数 / 权限	是	发送过于频繁：展示「发送太快」并退避。
`1009`	`GROUP_MUTED`	客户端 / 参数 / 权限	否	已被禁言：禁用输入区并提示禁言状态。
`1010`	`SENSITIVE_WORD`	客户端 / 参数 / 权限	否	内容含敏感词：提示修改后重发。
`1011`	`BLOCKED`	客户端 / 参数 / 权限	否	拉黑关系：提示无法发送。
`1012`	`CHATROOM_NOT_FOUND`	客户端 / 参数 / 权限	否	聊天室不存在：退出聊天室页面。
`1013`	`CHATROOM_CLOSED`	客户端 / 参数 / 权限	否	聊天室已销毁：返回会话列表。
`1014`	`NOT_CHATROOM_MEMBER`	客户端 / 参数 / 权限	否	未加入聊天室：先加入再发送。
`1015`	`MEMBERSHIP_LIMIT`	客户端 / 参数 / 权限	否	成员数量超限：提示群/聊天室容量已满。
`1016`	`USER_BANNED`	客户端 / 参数 / 权限	否	账号封禁：跳转申诉或客服。
`1017`	`APP_DISABLED`	客户端 / 参数 / 权限	否	应用停用：提示联系管理员。
`1022`	`RECALL_EXPIRED`	客户端 / 参数 / 权限	否	超过撤回时限：隐藏撤回菜单或提示失败。
`1023`	`MESSAGE_ALREADY_RECALLED`	客户端 / 参数 / 权限	否	消息已撤回：替换为撤回占位。
`1025`	`QUOTA_EXCEEDED`	客户端 / 参数 / 权限	是	超出配额：提示稍后重试。
`1026`	`MESSAGE_NOT_EXPANDABLE`	客户端 / 参数 / 权限	否	提示用户后允许重试。
`1027`	`EXPANSION_LIMIT_EXCEEDED`	客户端 / 参数 / 权限	否	提示用户后允许重试。
`1028`	`REACTION_INVALID`	客户端 / 参数 / 权限	否	提示用户后允许重试。
`1029`	`REACTION_LIMIT_EXCEEDED`	客户端 / 参数 / 权限	否	提示用户后允许重试。
`1030`	`REACTION_USER_LIMIT_EXCEEDED`	客户端 / 参数 / 权限	否	提示用户后允许重试。
`1031`	`TAG_LIMIT_EXCEEDED`	客户端 / 参数 / 权限	否	提示用户后允许重试。
`1032`	`TAG_NOT_FOUND`	客户端 / 参数 / 权限	否	提示用户后允许重试。
`1033`	`TAG_CONVERSATION_LIMIT_EXCEEDED`	客户端 / 参数 / 权限	否	提示用户后允许重试。
`1034`	`CONVERSATION_NOT_FOUND`	客户端 / 参数 / 权限	否	提示用户后允许重试。
`1035`	`MESSAGE_REJECTED_BY_CALLBACK`	客户端 / 参数 / 权限	否	提示用户后允许重试。
`3001`	`SDK_NOT_CONNECTED`	SDK 本地	是	长连接未就绪：展示离线状态并在 CONNECTED 后重试。
`3002`	`SDK_TIMEOUT`	SDK 本地	是	请求超时：展示重试按钮。
`3003`	`SDK_NETWORK_ERROR`	SDK 本地	是	网络错误：展示网络异常条，等待重连。
`3004`	`SDK_UNSUPPORTED`	SDK 本地	否	当前平台不支持该能力：降级或隐藏入口。

展示策略

场景	建议展示	组件入口
发送失败	气泡旁失败图标 + 点击重发	`MessageStatusIndicator`
连接断开	顶部网络异常条；CONNECTED 后自动消失	`ChatView` / 宿主页面
会话为空	空态插画 + 引导文案	`ConversationListView`
加载中	骨架屏 / loading 态	`ConversationListView`
被禁言	输入区禁用 + 提示	`MessageInput`
聊天室销毁	提示后返回会话列表	宿主路由

错误处理示例

const res = await client.sendTextMessage(1, 'user2', '你好，NI PaaS');
if (res.code !== 0) {
  if (res.code === 1009) showToast('你已被禁言');
  else if (res.code === 3001) showOfflineBanner();
  else markMessageFailed(res.code, res.msg);
}

把上述返回值映射为组件的状态属性（status / failed / disabled 等），不要直接弹原始错误码。

Web IMKit 状态码

返回信封与错误形态​

UI 相关状态码​

展示策略​

错误处理示例​

相关文档​

返回信封与错误形态

UI 相关状态码

展示策略

错误处理示例

相关文档