106 行
2.5 KiB
Markdown
106 行
2.5 KiB
Markdown
|
# 错误码文档
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## HTTP 错误码
|
|||
|
|
|
|||
|
|
| 状态码 | 说明 | 常见场景 |
|
|||
|
|
|--------|------|----------|
|
|||
|
|
| 200 | 成功 | 请求正常处理 |
|
|||
|
|
| 400 | 请求参数错误 | 缺少必填字段、参数类型不匹配 |
|
|||
|
|
| 401 | 未授权 | Token 无效、过期、未携带 |
|
|||
|
|
| 403 | 禁止访问 | 权限不足、黑名单限制 |
|
|||
|
|
| 404 | 资源不存在 | 用户不存在、群不存在、消息不存在 |
|
|||
|
|
| 500 | 服务端内部错误 | 异常未捕获 |
|
|||
|
|
|
|||
|
|
所有接口统一返回格式：
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"status": "OK",
|
|||
|
|
"data": { ... },
|
|||
|
|
"message": ""
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
业务错误时：
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"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 文档 →](./api)
|
