Flutter IMLib 状态码

客户端状态码来自 errors.json：1xxx 为客户端 / 参数 / 权限类，3xxx 为 SDK 本地错误（不来自服务端）；所有异步接口通过返回信封中的 code 表达失败，不用异常表示业务错误。

返回信封

层	信封	说明
客户端	`RcResult {code,data?,msg?}`	所有 IMLib 异步接口统一返回；成功 code=0
客户端（IDL 声明）	`RcResult<T> = {code:int, data?:T, msg?:string}`	来自 sdk-imlib.json → resultEnvelope
WebSocket	`Frame {id?,type:'error',data:{code,message}}`	协议层错误帧；SDK 会转换为 RcResult 错误码
Open API	`OpenApiResponse {code,msg?,data?,requestId?}`	服务端 REST；客户端内部按同一码表处理

错误码分类

码段	含义	处理建议
0	成功	—
1xxx	客户端 / 参数 / 权限类	不可重试（1008 / 1025 限频与配额除外）；修正参数或引导用户
2xxx	服务端 / 依赖类	可重试（退避重试）
3xxx	SDK 本地错误	多为可重试（连接未就绪、超时、网络）；3004 表示当前平台不支持该能力

客户端状态码

错误码	名称	HTTP	分类	可重试	中文文案
`1001`	`INVALID_PARAMETER`	400	客户端 / 参数 / 权限	否	参数错误
`1002`	`INVALID_TOKEN`	401	客户端 / 参数 / 权限	否	Token 无效或已过期
`1003`	`FORBIDDEN`	403	客户端 / 参数 / 权限	否	无权限
`1004`	`USER_NOT_FOUND`	404	客户端 / 参数 / 权限	否	用户不存在
`1005`	`GROUP_NOT_FOUND`	404	客户端 / 参数 / 权限	否	群组不存在
`1006`	`NOT_GROUP_MEMBER`	403	客户端 / 参数 / 权限	否	未加入群组
`1007`	`MESSAGE_TOO_LARGE`	400	客户端 / 参数 / 权限	否	消息体过大（上限 5KB）
`1008`	`RATE_LIMITED`	429	客户端 / 参数 / 权限	是	发送过于频繁
`1009`	`GROUP_MUTED`	403	客户端 / 参数 / 权限	否	你已被禁言
`1010`	`SENSITIVE_WORD`	400	客户端 / 参数 / 权限	否	内容包含敏感词
`1011`	`BLOCKED`	403	客户端 / 参数 / 权限	否	已被对方拉黑或你已拉黑对方
`1012`	`CHATROOM_NOT_FOUND`	404	客户端 / 参数 / 权限	否	聊天室不存在
`1013`	`CHATROOM_CLOSED`	410	客户端 / 参数 / 权限	否	聊天室已销毁
`1014`	`NOT_CHATROOM_MEMBER`	403	客户端 / 参数 / 权限	否	未加入聊天室
`1015`	`MEMBERSHIP_LIMIT`	400	客户端 / 参数 / 权限	否	成员数量超出上限
`1016`	`USER_BANNED`	403	客户端 / 参数 / 权限	否	账号已被封禁
`1017`	`APP_DISABLED`	403	客户端 / 参数 / 权限	否	应用已停用
`1022`	`RECALL_EXPIRED`	400	客户端 / 参数 / 权限	否	超过撤回时限
`1023`	`MESSAGE_ALREADY_RECALLED`	400	客户端 / 参数 / 权限	否	消息已撤回
`1025`	`QUOTA_EXCEEDED`	429	客户端 / 参数 / 权限	是	超出配额
`1026`	`MESSAGE_NOT_EXPANDABLE`	400	客户端 / 参数 / 权限	否	消息不可扩展（发送时未开启可扩展，或会话类型不支持）
`1027`	`EXPANSION_LIMIT_EXCEEDED`	400	客户端 / 参数 / 权限	否	消息扩展超出限制（单次 20 对 / 单条 300 对 / 键值长度）
`1028`	`REACTION_INVALID`	400	客户端 / 参数 / 权限	否	回应标识非法（1-16 字符）
`1029`	`REACTION_LIMIT_EXCEEDED`	400	客户端 / 参数 / 权限	否	单条消息回应种类超出上限（50）
`1030`	`REACTION_USER_LIMIT_EXCEEDED`	400	客户端 / 参数 / 权限	否	单个回应参与用户超出上限（100）
`1031`	`TAG_LIMIT_EXCEEDED`	400	客户端 / 参数 / 权限	否	单用户会话标签数超过上限（20）
`1032`	`TAG_NOT_FOUND`	404	客户端 / 参数 / 权限	否	标签不存在
`1033`	`TAG_CONVERSATION_LIMIT_EXCEEDED`	400	客户端 / 参数 / 权限	否	标签内会话数超过上限（1000）
`1034`	`CONVERSATION_NOT_FOUND`	404	客户端 / 参数 / 权限	否	会话不存在（标签内置顶等操作要求会话已在标签内）
`1035`	`MESSAGE_REJECTED_BY_CALLBACK`	403	客户端 / 参数 / 权限	否	发送前同步回调拒绝该消息（应用服务器返回 action=block，或降级配置为 block）
`3001`	`SDK_NOT_CONNECTED`	0	SDK 本地	是	长连接未就绪
`3002`	`SDK_TIMEOUT`	0	SDK 本地	是	请求超时
`3003`	`SDK_NETWORK_ERROR`	0	SDK 本地	是	网络错误
`3004`	`SDK_UNSUPPORTED`	0	SDK 本地	否	当前平台不支持该能力

IMLib 操作引用码

客户端 103 个语义操作共引用 34 个错误码（并集），下表给出处理建议。

错误码	名称	可重试	处理建议
`1001`	`INVALID_PARAMETER`	否	修正参数后重试；不可重试。
`1002`	`INVALID_TOKEN`	否	重新获取 Token 后重连；不要循环重试旧 Token。
`1003`	`FORBIDDEN`	否	修正后重试；不可自动重试。
`1004`	`USER_NOT_FOUND`	否	修正后重试；不可自动重试。
`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`	否	提示应用停用；联系管理员。
`1021`	`SERVICE_NOT_ACTIVATED`	否	修正后重试；不可自动重试。
`1022`	`RECALL_EXPIRED`	否	修正后重试；不可自动重试。
`1023`	`MESSAGE_ALREADY_RECALLED`	否	修正后重试；不可自动重试。
`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`	否	修正后重试；不可自动重试。
`2001`	`INTERNAL_ERROR`	是	退避后重试。
`2002`	`DEPENDENCY_UNAVAILABLE`	是	退避后重试。
`3001`	`SDK_NOT_CONNECTED`	是	等待 CONNECTED 后重试；先检查连接状态。
`3002`	`SDK_TIMEOUT`	是	超时重试一次；持续超时检查网络与服务端可达性。
`3003`	`SDK_NETWORK_ERROR`	是	网络错误：重连成功后重试。

错误处理示例

final code = await engine.connect(TOKEN, 10);
switch (code) {
  case 0: break;
  case 1002: /* Token 无效/过期：不自动重连，提示重新登录 */ break;
  case 1003: /* 无权限/被禁用：不自动重连 */ break;
  case 3001:
  case 3002: /* 传输层/超时：SDK 按退避策略自动重连 */ break;
  default: print('connect failed: ${code}');
}

Flutter IMLib 状态码

返回信封​

错误码分类​

客户端状态码​

IMLib 操作引用码​

错误处理示例​

相关文档​

返回信封

错误码分类

客户端状态码

IMLib 操作引用码

错误处理示例

相关文档