错误信息对照表
页面或接口报错时，先按错误标识查表，再按说明处理。排查时记录请求 ID，便于查日志。
怎么找到请求 ID
报错提示条或弹窗里通常会带一串编号，形如 req_... 或一串短横线分段的字符。找不到时：
- 打开浏览器开发者工具（F12）；
- 切到 Network 面板；
- 触发一次失败操作；
- 点开红色状态的请求，看响应头中的请求 ID。
向他人求助时提供请求 ID、时间、操作步骤和 Novora 版本，但不要附连接串、密码或完整请求头。
登录与账号
| 错误标识 | 含义 | 怎么处理 |
|---|---|---|
INVALID_CREDENTIALS | 用户名或密码不对 | 确认用户名大小写与密码；仍失败则重置密码 |
PASSWORD_CHANGE_REQUIRED | 首次登录或刚被重置，必须先设置新凭据 | 按页面提示设置新用户名和新密码 |
ACCOUNT_LOCKED | 连续错误触发锁定 | 等待锁定时长，或由上级管理员重置密码 |
SESSION_EXPIRED | 会话过期或令牌无效（HTTP 401） | 重新登录 |
EMAIL_NOT_BOUND | 该邮箱未绑定任何管理员账号 | 先在「我的账户」绑定邮箱 |
EMAIL_CODE_INVALID | 验证码错误、过期或已使用 | 重新获取；验证码 5 分钟内有效且只能用一次 |
EMAIL_RATE_LIMITED | 发送太频繁（同邮箱 60 秒、同 IP 每小时有限制） | 等待后再试 |
AUTH_REQUIRED | 未登录访问受限接口 | 先登录 |
权限与范围
| 错误标识 | 含义 | 怎么处理 |
|---|---|---|
PERMISSION_DENIED | 当前角色没有该模块权限，或数据范围不含该对象（HTTP 403） | 不要反复重试；由超级管理员检查角色与范围 |
SCOPE_DENIED | 操作对象不在授权年级或班级内 | 确认当前账号的授权范围 |
ROLE_IMMUTABLE | 试图修改内置角色 | 内置角色不可改，需要时新建自定义角色 |
LAST_SUPER_ADMIN | 试图删除或降级最后一个超级管理员 | 先新增一个超级管理员再操作 |
考试与周测
| 错误标识 | 含义 | 怎么处理 |
|---|---|---|
ILLEGAL_STATE | 当前状态不允许该操作（例如没开考就申请停止、已经申请过还在重复提交） | 看考试详情的时间线确认真实状态 |
ILLEGAL_TRANSITION | 非法的状态跳转 | 按当前约定操作：创建即发布 → 到点系统自动开考 → 申请停止（或强制结束）→ 归档 |
EXAM_NOT_FOUND | 考试记录不存在或已被删除 | 刷新列表确认 |
EXAM_ALREADY_STARTED | 考试已开考 | 开考由系统按计划时间完成；需要调整时用暂停、继续或延长 |
EXAM_NOT_PAUSED | 考试当前不在暂停中 | 不能直接点继续 |
MISSING_ARGUMENT | 缺少必要参数（例如延长未填分钟数） | 补充参数；延长范围是 1–600 分钟 |
IDEMPOTENCY_KEY_REUSED | 同一个操作标识被用于不同的操作 | 重新发起一次操作，不要复用旧请求 |
IDEMPOTENCY_KEY_REQUIRED | 复制或延长考试时未提供操作标识 | 通过界面正常操作即可，界面会自动带上 |
EXAM_TIME_OVERLAP | 与已启用科目时间重叠 | 先确认不是日期或上午下午填错，确实允许并行再确认 |
EXAM_TOO_LONG | 单科超过 6 小时 | 确认是跨天或特殊安排；否则检查结束日期 |
PLAN_NOT_ACTIVE | 周测计划未启用或不在生效期 | 检查计划的启用状态和生效日期 |
数据与版本
| 错误标识 | 含义 | 怎么处理 |
|---|---|---|
VERSION_CONFLICT | 内容已被其他设备修改 | 查看最新内容后再决定保留哪一版 |
SCHEMA_VERSION_MISMATCH | 数据库结构与代码版本不匹配 | 通常出现在升级中断；查日志后重试一次升级 |
VALIDATION_FAILED | 提交的数据格式不合法 | 按提示检查具体字段 |
RATE_LIMITED | 请求过于频繁（HTTP 429） | 稍后重试，不要连续点击 |
DATABASE_UNAVAILABLE | 数据库连不上 | 云端查 Neon 状态，本地查数据库容器或服务 |
设备与插件
| 错误标识 | 含义 | 怎么处理 |
|---|---|---|
DEVICE_NOT_FOUND | 设备不存在或已解绑 | 回首页重新选择班级 |
DEVICE_ALREADY_BOUND | 该设备已绑定到其他班级 | 先在设备管理解除旧绑定 |
PAIR_TOKEN_INVALID | 配对令牌无效 | 重新发起配对 |
PAIR_TOKEN_EXPIRED | 配对令牌过期（有效期 5 分钟） | 回到插件重新开始配对 |
PLUGIN_KEY_REVOKED | 插件凭据已被撤销 | 插件需要重新配对 |
CLASS_NOT_FOUND | 班级不存在或已删除 | 确认年级班级结构 |
部署与更新
| 错误标识 | 含义 | 怎么处理 |
|---|---|---|
NO_HOOK | 运行中的服务未读到部署钩子变量 | 确认 VERCEL_DEPLOY_HOOK_URL 已填写并重新部署 |
DEPLOY_HOOK_FAILED | 触发部署失败（非 2xx） | 检查钩子是否被删除、分支是否存在、URL 是否完整 |
MISSING_ENV | 缺少必需的环境变量 | 检查配置后重新部署（环境变量只对新部署生效） |
MISSING_DATABASE_URL | 未配置数据库连接串 | 本地部署必填 DATABASE_URL |
UPDATE_CHECK_UNAVAILABLE | 版本检查服务不可用 | 内网环境会正常降级；不影响核心功能 |
TELEMETRY_DISABLED | 遥测未开启或已被跳过 | 不是错误；需要时在系统设置中开启 |
同步与网络
| 现象 | 含义 | 怎么处理 |
|---|---|---|
| 一直显示「正在同步」 | 请求未返回或网络中断 | 检查能否打开 /api/time；刷新后重试 |
| 「同步失败」 | 请求被拒绝或超时 | 改动仍在本地队列；按提示重试，不要清缓存 |
CORS_REJECTED | 同源校验失败 | 本地部署检查反向代理是否转发 X-Forwarded-Host 与 X-Forwarded-Proto |
NETWORK_ERROR | 请求未到达服务端 | 检查域名、HTTPS 和网络连通性 |
TIMEOUT | 服务端响应超时 | 稍后重试；持续出现时查日志 |
HTTP 状态码速查
| 状态码 | 常见含义 |
|---|---|
| 400 | 请求参数有问题 |
| 401 | 未登录或会话过期，重新登录 |
| 403 | 已登录但没有权限或数据范围 |
| 404 | 地址或对象不存在 |
| 405 | 请求方法不允许（例如对只读接口发起了写操作） |
| 409 | 状态冲突（版本冲突、非法状态跳转、重复操作） |
| 429 | 请求过于频繁 |
| 5xx | 服务端问题，查请求 ID 与日志 |
还是解决不了
不要发送的内容
数据库连接串、管理员密码、Deploy Hook URL、恢复密钥和完整请求头。这些一旦发出就应视为泄露，需要立即轮换。