API 参考
圈组

状态码/错误码

更新时间: 2024/07/17 17:57:34

本文介绍 IM 的状态码/错误码、对应的排查方法以及出现部分状态码/错误码的典型场景。对于部分错误码,您也可以在 KB 知识库 中直接搜索错误码编号并查看详细说明。

服务端状态码

IM 通用状态码

code 详细描述 排查指引
200 操作成功 -
201 客户端版本不对,需升级 SDK -
300 用户未被邀请 -
301 被封禁 -
302 用户名或密码错误 详见状态码302
305 要注销的账号不存在 -
306 token 失效 -
310 登录IP或MAC被封锁 -
315 IP限制 -
316 用户名不存在或密码错误 -
320 域名不存在 -
321 域名被禁用 -
398 请求临时禁止 -
399 请求 IM 目标单元错误 请按照接入海外单元的流程接入目标单元
403 非法操作或没有权限 详见状态码403
404 对象不存在 详见状态码404
405 参数长度过长 -
406 对象只读 -
408 客户端请求超时 详见状态码408
413 验证失败(短信服务) -
414 参数错误 详见状态码414
415 客户端网络问题 -
416 频率控制 调用频次超过接口本身限制频次
417 重复操作 详见状态码417
418 通道不可用(短信服务) -
419 数量超过上限 -
420 操作出现异常 -
421 权限被取消 -
422 账号被禁用 -
423 账号被禁言 -
430 账号过期 -
431 HTTP重复请求 -
449 请求需要重试 此次请求触发了分布式锁
500 服务器内部错误 -
501 数据库操作失败 -
503 服务器繁忙 -
508 消息撤回时间超限 -
509 无效协议 -
510 用户不存在 -
511 App 不可达 -
512 GATE 不可达 -
513 YIXIN 不可达 -
514 服务不可用 -
599 协议被黑洞规则过滤 -
998 解包错误 -
999 打包错误 -
7101 消息发送方被接收方设置为黑名单 -

群相关错误码

code
详细描述 排查指引
801 群人数达到上限 如果「单次邀请进群人数」大于「群最高人数」减去「群内已有人数」时,会返回错误码801,该次邀请的账号全都无法入群。
802 没有权限 详见状态码802
803 群不存在 -
804 用户不在群 -
805 群类型不匹配 -
806
  • 创建群时群成员数超出限制
  • 创建群组数量已达上限
  • 创建群组时,「邀请进群人数」大于「群最高人数」,会返回错误码 806,该群组创建失败。
  • 创建群组数量已达上限,会返回错误码 806,该群组创建失败。
  • 群组功能的具体业务限制请参见限制说明
    807 群成员状态错误 调用接收入群邀请接口前,必须先触发邀请的动作
    808 申请成功 -
    809 已经在群内 -
    810 邀请成功 -
    811 @账号数量超过限制 -
    812 群禁言,普通成员不能发送消息 -
    813 群拉人部分成功 -
    814 禁止使用群组已读服务 -
    815 群管理员人数超过上限 -
    816 群信息获取部分成功 失败列表会返回 -
    997 appid没权限调用该协议 -

    聊天室相关错误码

    code 详细描述 排查指引
    13001 IM主连接状态异常 -
    13002 聊天室状态异常 -
    13003 账号在黑名单中,不允许进入聊天室 -
    13004 在禁言列表中,不允许发言 -
    13005 用户的聊天室昵称、头像或成员扩展字段被反垃圾 -
    13006 聊天室处于整体禁言状态,只有管理员能发言 -
    13007 因单个聊天室高频引起消息被过滤投递 -
    13008 在禁言标签中 -

    协议相关错误码

    code 详细描述 排查指引
    6101 转码解析失败 -
    6102 语音时长超过设置 -
    6103 服务不可用 -
    6104 audiourl不合法 -
    6105 图片处理,调用nos api时出错 -
    6106 图片处理,当前配置不允许一次多个图片操作 -

    特定业务相关错误码

    code 详细描述 排查指引
    10431 输入email不是邮箱 -
    10432 输入mobile不是手机号码 -
    10433 注册输入的两次密码不相同 -
    10434 企业不存在 -
    10435 登陆密码或账号不对 -
    10436 app不存在 -
    10437 email已注册 -
    10438 手机号已注册 -
    10441 app名字已经存在 -

    信令错误码

    code 详细描述 排查指引
    10404 房间不存在 -
    10405 房间已存在 -
    10406 不在房间内 -
    10407 已经在房间内 -
    10408 邀请不存在或已过期 -
    10409 邀请已经拒绝 -
    10410 邀请已经接受了 -
    10201 对方云信不在线 -
    10202 对方云信不在线,且推送也不可达 -
    10419 房间人数超限 -
    10420 已经在房间内(自己的其他端) -
    10417 uid冲突 -

    音视频、白板通话相关错误码

    code 详细描述 排查指引
    9102 通道失效 -
    9103 已经在他端对这个呼叫响应过了 -
    9104 call master 用户已经auth过了 -
    11001 通话不可达,对方离线状态 -

    状态码详解

    用户名或密码错误302

    当客户端SDK执行登录后,回调状态码302时,请检查当前的AppKey、accid(accout)与token三者是否一一对应。较常见的原因如:token不正确或不是最新、该AppKey下无此accid等。
    详情参见关于IM登录失败-返回302

    非法操作或没有权限403

    当执行非法操作时,会返回状态码403。常见的非法操作如下:

    非法操作类型 说明
    未开通/启用功能 未开通事件订阅(常用于在线事件订阅)的情况下,使用相关功能,会返回 403
    云信控制台上当前 AppKey 对应的应用已关停时,调用 IM 服务端 API 会返回{"desc": "app is forbidden", "code": 403}
    如果当前应用无收发 IM 消息的权限(在云信控制台会有相应提示),调用发消息的接口时,会返回 403。具体请咨询商务经理
    删除漫游消息时,如果应用下没有开启消息漫游功能,调用相关接口会返回403

    对象不存在404

    当调用接口回调出404状态码后,请检查传参是否正确,常见的情况如:

    • 必传参数为空时,可能会回调404。
    • 传入的参数实际不存在。如传入实际上未注册过的accid,不存在的群id等。

    客户端请求超时408

    当调用接口回调出408状态码后,请检查当前所处的网络是否正常。常见的情况如:

    • 网络连接断开后,调用联网请求接口,此时会回调408。
    • 在未成功登录的情况下,调用联网请求接口。
    • Android SDK 4.3.0及之前的版本,没有对于Android 8.0以上系统版本的适配,登录时可能出现408,请更新到最新版本SDK。

    参数错误414

    问题类型 说明
    请求配置 传参的数据类型与接口要求不一致
    传入未注册过的云信 IM 账号(accid)时
    请求头校验信息错误(注:计算CheckSum时使用的是 App Secret 而不是 App Key。)。关于校验信息,请点此查看
    传入的CurTime参数与当前 UTC 时间戳不一致(超前或滞后),返回{"desc": "CurTime is illegal", "code": 414}/{"desc": "CurTime is expired", "code": 414},可能原因是:
    • 没有实时动态获取当前 UTC 时间戳
    • 应用服务器配置的时区和时间与实际不一致
    请求的 Content-Type 错误,返回{"desc":"body not json", "code":414}。IM 服务端 API 请求的 Content-Type 为application/x-www-form-urlencoded,请对参数值进行 URL encode,避免特殊字符造成解析失败。
    云信IM账号 调用注册云信IM账号并发创建账号时,不同的请求传入相同的accid参数可能返回{"desc":"retry again", "code":414}
    调用注册云信IM账号时,返回{"desc": "Exceed the maximum account XXX", "code":414}。可能原因有:
    • IM 免费版账号数上限数为 100 个
    • IM 套餐包试用到期。IM 试用期间账号数无上限,试用到期后上限数降为 100 个。若需继续使用 IM 正式版,请联系商务经理开通正式版
    登录 登录时配置的 customTag 字段超过 32 个字符
    群组 Web SDK中,群已读回执功能里,参数teamMsgReceipts为数组格式,数组元素上限数 50,超过会返回 414
    如果群主账号被封禁后,再调用服务端 API 解散群,会返回{"desc": "check accid001", "code": 414}
    聊天室 如果聊天室被关闭,查询聊天室消息历史会返回 414。例如:调用 IM 服务端API「聊天室云端历史消息查询」会返回{"desc": "check roomid", "code": 414}
    调用聊天室相关 API 返回{"desc":"parameter roomid should be long","code":414},可能原因包括但不限于:对roomid参数的值进行了误编码,例如PHP中对其进行 json_encode 可能导致出现此报错
    更新聊天室信息时,如果只传入roomidneedNotifynotifyExt,而没有传入其它任何需要更新的参数,则会返回{"desc": "no valid param provided, skip update!", "code": 414}
    好友关系 不能添加自己为好友,否则返回 414
    云信控制台配置 如果在云信控制台 > 应用 > App Key管理 > 标识管理,选中了进行标识安全验证,当客户端App标识(iOS Bundle Identifier / Android Package Name)不在配置的列表中,登录请求将被拒绝,返回错误码414
    内容审核 消息内容被安全通检测到包含敏感词,尝试撤回时,会返回错误码 414
    短信 调用短信相关接口时,若开发者传入的参数不符合JSON格式会返回{"code": 414, "msg": "'mobiles' / 'params' should be json format"}

    重复操作417

    • 客户端自动登录时,回调417。可能原因参见自动登录返回417
    • 创建多人音视频房间,回调417.可能原因参见关于多人音视频/互动直播房间的注意事项
    • IM服务端API设置聊天室内用户角色返回{desc:"duplicate...", code:"417"},可能原因包括但不限于:
      • 重复操作,例如已经设置某角色之后再次设置,或者已经取消某角色之后再次取消。
      • 设置不当,例如对非管理员角色取消管理员,或者对非聊天室成员进行操作等。

    没有权限802

    • 调用IM SDK主动退群接口,返回802。高级群的群主不能直接退群,可以先转让群再退群,或者直接解散群。
    • 调用将群组整体禁言接口设置或解除群组禁言时,如果muteType传入3,表示禁言整个群(包括群主)。这种情况下如果SDK/客户端若再尝试调用禁言接口,会返回802。
    此文档是否对你有帮助?
    有帮助
    去反馈
    • 服务端状态码
    • IM 通用状态码
    • 群相关错误码
    • 聊天室相关错误码
    • 协议相关错误码
    • 特定业务相关错误码
    • 信令错误码
    • 音视频、白板通话相关错误码
    • 状态码详解
    • 用户名或密码错误302
    • 非法操作或没有权限403
    • 对象不存在404
    • 客户端请求超时408
    • 参数错误414
    • 重复操作417
    • 没有权限802