XuqmGroup-Web/docs-site/docs/server/errors.md

# 错误码文档

---

## 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 不能为空"
}
```

---

## IM 连接错误码

| 关闭码 | 说明 | 处理建议 |
|--------|------|----------|
| 1000 | 正常关闭 | 无需重连（如用户主动登出）|
| 1001 | 服务端关闭 | 尝试重连 |
| 1006 | 异常断开 | 自动重连 |
| 1008 | 策略违反（如 Token 无效）| 重新获取 Token 后重连 |
| 1011 | 服务端异常 | 指数退避重连 |

---

## SDK 错误码

### Android

| 错误 | 说明 |
|------|------|
| `XuqmSDK not initialized. Call XuqmSDK.initialize() first.` | 未调用初始化 |
| `IM 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.` | 未调用初始化 |
| `IM not connected` | IM 未连接时发送消息 |
| `IM token is empty` | 未登录或 Token 已清空 |

---

## 常见错误排查

### Q: 登录后 IM 无法连接

- 检查 `userSig` 是否有效（未过期、签名正确）
- 检查网络是否允许长连接（防火墙、代理）
- 检查 IM 连接地址是否正确

### Q: 发送消息返回 FAILED

- 检查 IM 连接状态
- 检查 `toId` 是否有效
- 检查 `appKey` 是否正确配置

### Q: 收不到消息

- 确认已订阅 `/user/queue/messages`
- 确认发送方和接收方使用同一 `appKey`
- 检查是否被对方拉黑

### Q: Token 401

- `userSig` 由服务端用 `appSecret` 签发，确保签名算法一致
- 检查 Token 是否在有效期内
- 检查 HTTP Header 中 `Authorization: Bearer {token}` 格式

[→ Server API 文档 →](/server/api)