状态码对照与覆盖
融云 iOS 状态码目录共 440 条（每条含码值、符号名、中文说明与排查建议，IMLib 与 IMKit 共用），已整理为兼容枚举；本项目运行时码表 errors.json 共 43 条（客户端 / SDK 34 条、服务端业务码 9 条）。两套编号体系不是一一对应：439 条兼容枚举、0 条运行时同码同义、1 条同码不同义。
口径
运行时以本项目码表为准：兼容枚举只用于旧常量兼容，线上排障请看运行时返回的 code / msg。
逐行对照见 状态码全量对照（440 条）；同码不同义的行已单独标注。
码表扩充属于契约变更，随 IDL 版本发布；对照页由参考目录与 errors.json 自动生成，不手写行。
覆盖总览
| 项 | 数量 | 说明 |
|---|---|---|
| 运行时码表（errors.json） | 43 | 状态码页逐条说明 |
| 参考目录（融云 iOS） | 440 | 兼容枚举全集 |
| 运行时同码同义 | 0 | 可直接按运行时语义处理 |
| 同码不同义 | 1 | 码值相同但语义不同，必须按本项目码表处理 |
| 兼容枚举 | 439 | SDK 保留常量，运行时不会返回这些码值 |
| 逐行对照 | 440 | 状态码全量对照 |
运行时码表分布
| 码段 | 含义 | 本项目收录 | 说明 |
|---|---|---|---|
| 1xxx | 客户端 / 参数 / 权限类 | 35 | 入参、Token、权限、限频、配额等 |
| 2xxx | 服务端 / 依赖类 | 4 | 服务端业务与依赖错误 |
| 3xxx | SDK 本地错误 | 4 | 连接未就绪、超时、网络、能力不支持 |
| 合计 | — | 43 | 参考目录 440 条为兼容枚举 |
客户端 / SDK 码表（与状态码页一致）
| 错误码 | 符号名 | 分类 | 可重试 | 说明 |
|---|---|---|---|---|
1001 | INVALID_PARAMETER | 客户端 | 否 | 参数错误 |
1002 | INVALID_TOKEN | 客户端 | 否 | Token 无效或已过期 |
1003 | FORBIDDEN | 客户端 | 否 | 无权限 |
1004 | USER_NOT_FOUND | 客户端 | 否 | 用户不存在 |
1005 | GROUP_NOT_FOUND | 客户端 | 否 | 群组不存在 |
1006 | NOT_GROUP_MEMBER | 客户端 | 否 | 未加入群组 |
1007 | MESSAGE_TOO_LARGE | 客户端 | 否 | 消息体过大（上限 5KB） |
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 | 客户端 | 否 | 消息扩展超出限制（单次 20 对 / 单条 300 对 / 键值长度） |
1028 | REACTION_INVALID | 客户端 | 否 | 回应标识非法（1-16 字符） |
1029 | REACTION_LIMIT_EXCEEDED | 客户端 | 否 | 单条消息回应种类超出上限（50） |
1030 | REACTION_USER_LIMIT_EXCEEDED | 客户端 | 否 | 单个回应参与用户超出上限（100） |
1031 | TAG_LIMIT_EXCEEDED | 客户端 | 否 | 单用户会话标签数超过上限（20） |
1032 | TAG_NOT_FOUND | 客户端 | 否 | 标签不存在 |
1033 | TAG_CONVERSATION_LIMIT_EXCEEDED | 客户端 | 否 | 标签内会话数超过上限（1000） |
1034 | CONVERSATION_NOT_FOUND | 客户端 | 否 | 会话不存在（标签内置顶等操作要求会话已在标签内） |
1035 | MESSAGE_REJECTED_BY_CALLBACK | 客户端 | 否 | 发送前同步回调拒绝该消息（应用服务器返回 action=block，或降级配置为 block） |
3001 | SDK_NOT_CONNECTED | SDK 本地 | 是 | 长连接未就绪 |
3002 | SDK_TIMEOUT | SDK 本地 | 是 | 请求超时 |
3003 | SDK_NETWORK_ERROR | SDK 本地 | 是 | 网络错误 |
3004 | SDK_UNSUPPORTED | SDK 本地 | 否 | 当前平台不支持该能力 |
差异与处理
| 差异类别 | 示例 | 客户端处理 |
|---|---|---|
| 能力相关码（未纳入当前码表） | RTC / 音视频、桌面端特有能力的错误 | 按错误码原值展示通用提示；不要映射成 0 或网络错误 |
| 推送通道码 | APNs 投递失败、证书/环境错误 | 服务端日志排查；客户端仅处理“未收到通知”的展示兜底 |
| 服务端业务细分码 | 更多业务校验分支 | 透传 code + msg，记录上报，等待码表扩充 |
| 旧版本码 | 历史码已废弃 / 合并 | 按当前码表处理；未知码保留原值 |
排障流程
- 先看 `code` 与 `msg`，确认是客户端码还是服务端码。
- 客户端码：按「状态码」页的重试建议处理（1002 换 Token、3001 等连接、3002/3003 退避）。
- 服务端码：记录 requestId（若有）与服务端日志，按业务含义提示用户。
- 未知码：保留原值 + 场景 + 版本，提交文档反馈，等待码表扩充。