错误处理

Flutter SDK 使用 MixinImException 表达稳定错误，包含 code、可读说明、可选追踪 ID 和可恢复标记。页面提示、自动重试和诊断记录应分别处理。

常见类别

错误码	含义	处理方式
not_initialized	尚未初始化	修正调用顺序
already_initialized	同一实例使用了不同初始化配置	复用配置或创建正确的新实例
invalid_session	用户或 Token 无效	核对业务后端返回
invalid_session_binding	设备或平台绑定不合法	核对当前设备与 Session
session_unavailable	当前能力缺少有效登录用户	等待用户连接完成
authentication_required	无法完成认证恢复	进入宿主重新登录流程
network_error	HTTP 网络失败	根据可恢复标记与业务场景重试
websocket_connect_failed	长连接建连失败	核对入口、网络和证书
message_rejected	服务端明确拒收消息	呈现业务原因，停止无意义重发
invalid_message_content	消息内容不符合要求	修正类型和内容
database_in_use	同一数据空间被活动实例占用	先释放旧实例，不抢占或删除库

具体可用错误以所用平台和交付版本为准。Call SDK 还包括 call_peer_blocked、call_relationship_denied 等关系或隐私拒绝，见 通话流程。

页面与业务分工

SDK 不负责跳转到你产品的登录页。宿主应监听鉴权状态，停止旧账号依赖的界面和请求，然后显示登录入口。网络临时失败时可保留页面与已有缓存，不要一律清空账号。

面向用户的提示应简洁，例如“连接暂不可用”或“当前没有发送权限”。技术错误码和追踪 ID 放到诊断信息里，不直接把完整异常对象、服务地址和响应 JSON 展示给用户。

重试原则

• 可恢复网络故障交给 SDK 连接恢复；不要同时开启多套重连循环。
• 消息或业务写入重试保留原逻辑动作身份。
• 签名、权限、参数和明确的终态拒绝先修正原因。
• 数据库密钥或迁移失败应保留原数据并处理错误，不用重建空库掩盖问题。

服务端错误

Server API 同时可能有 HTTP 状态与业务响应结果，不能只看 HTTP 200 就认定业务成功。先识别签名与权限问题，再分析参数、成员关系、状态限制和部署依赖。

提交联调问题时提供发生时间、平台版本、操作步骤、稳定错误码及已脱敏的追踪 ID。更多定位顺序见 故障排查。