错误码文档
HTTP 错误码
| 状态码 |
说明 |
常见场景 |
| 200 |
成功 |
请求正常处理 |
| 400 |
请求参数错误 |
缺少必填字段、参数类型不匹配 |
| 401 |
未授权 |
Token 无效、过期、未携带 |
| 403 |
禁止访问 |
权限不足、黑名单限制 |
| 404 |
资源不存在 |
用户不存在、群不存在、消息不存在 |
| 500 |
服务端内部错误 |
异常未捕获 |
所有接口统一返回格式：
{
"code": 200,
"status": "OK",
"data": { ... },
"message": ""
}
业务错误时：
{
"code": 400,
"status": "BAD_REQUEST",
"data": null,
"message": "参数错误：userId 不能为空"
}
WebSocket 错误码
| 关闭码 |
说明 |
处理建议 |
| 1000 |
正常关闭 |
无需重连（如用户主动登出） |
| 1001 |
服务端关闭 |
尝试重连 |
| 1006 |
异常断开 |
自动重连 |
| 1008 |
策略违反（如 Token 无效） |
重新获取 Token 后重连 |
| 1011 |
服务端异常 |
指数退避重连 |
SDK 错误码
Android
| 错误 |
说明 |
XuqmSDK not initialized. Call XuqmSDK.initialize() first. |
未调用初始化 |
WebSocket not connected |
发送消息时未连接 |
edit message failed |
编辑消息接口返回空 |
revoke message failed |
撤回消息接口返回空 |
iOS
| 错误 |
说明 |
XuqmSDK not initialized. Call XuqmSDK.shared.initialize() first. |
未调用初始化 |
Web / Vue3 / 小程序
| 错误 |
说明 |
XuqmSDK not initialized. Call init() first. |
未调用初始化 |
WebSocket not connected |
WebSocket 未连接时发送消息 |
IM token is empty |
未登录或 Token 已清空 |
常见错误排查
Q: 登录后 WebSocket 无法连接
- 检查
userSig 是否有效（未过期、签名正确）
- 检查网络是否允许 WebSocket（防火墙、代理）
- 检查 WebSocket 地址是否正确
Q: 发送消息返回 FAILED
- 检查 WebSocket 连接状态
- 检查
toId 是否有效
- 检查
appKey 是否正确配置
Q: 收不到消息
- 确认已订阅
/user/queue/messages
- 确认发送方和接收方使用同一
appKey
- 检查是否被对方拉黑
Q: Token 401
userSig 由服务端用 appSecret 签发，确保签名算法一致- 检查 Token 是否在有效期内
- 检查 HTTP Header 中
Authorization: Bearer {token} 格式
→ Server API 文档 →
6cd938cfbc
