LyEdu 错误码说明
编辑日期：2026-02-26
基于 ly-edu 项目 API 设计整理
一、HTTP 状态码
| 状态码 | 说明 |
|---|---|
| 200 | 请求成功 |
| 201 | 创建成功 |
| 204 | 删除成功，无返回内容 |
| 400 | 请求参数错误 |
| 401 | 未认证或 Token 失效 |
| 403 | 无权限访问 |
| 404 | 资源不存在 |
| 409 | 冲突（如重复创建） |
| 422 | 数据校验失败 |
| 500 | 服务器内部错误 |
二、业务错误码（通用）
API 响应体中 code 字段表示业务状态，message 为可读描述：
| 错误码 | 说明 | 处理建议 |
|---|---|---|
| 0 | 成功 | - |
| 400 | 请求参数错误 | 检查请求体、查询参数格式与必填项 |
| 401 | 未认证 | 重新登录获取 Token |
| 403 | 无权限 | 检查用户角色与接口权限 |
| 404 | 资源不存在 | 确认 ID、路径是否正确 |
| 500 | 服务器错误 | 查看服务端日志，联系维护人员 |
三、认证相关
| 错误信息 | 可能原因 | 处理方式 |
|---|---|---|
| Invalid token / Token expired | Token 无效或过期 | 重新登录 |
| Invalid username or password | 用户名或密码错误 | 核对账号密码 |
| Feishu callback failed | 飞书回调失败 | 检查 App 配置、回调地址、state |
| User not found | 用户不存在 | 检查用户是否已同步或创建 |
四、业务模块常见错误
课程 / 学习
- 课程不存在：确认课程 ID，检查是否已删除
- 章节不存在：确认章节 ID 属于当前课程
- 视频未上传：等待上传完成或重新上传
- 学习进度保存失败：检查网络与后端状态
考试
- 考试已结束：考试已过截止时间
- 考试未开始：未到开始时间
- 已提交：该用户已交卷，不可重复提交
- 题目不存在：试卷中题目可能已删除或变更
用户 / 部门
- 用户名已存在：注册或添加时用户名重复
- 部门不存在：部门 ID 错误或已删除
- 部门层级错误：父部门选择不合法
文件上传
- 文件类型不支持：检查允许的 MIME 类型
- 文件过大：超过配置的大小限制
- 存储失败：检查磁盘空间与存储配置
五、调试建议
- 查看响应体：
code、message、detail通常包含具体原因 - 查看网络：浏览器开发者工具 Network 面板
- 查看日志：后端日志有堆栈与详细错误
- 接口文档：Swagger/OpenAPI 文档中有参数与响应说明
六、统一错误响应示例
json
{
"code": 400,
"message": "用户名已存在",
"detail": "username: admin"
}具体字段以实际 API 为准。