ERROR CODES / REFERENCE
错误码对照。
遇到 4xx/5xx 时，按错误码查这里。若仍无法解决，携带错误码与支持联系。
400
| 错误码 | 含义 | 怎么处理 |
|---|
EMAIL_INVALID | 邮箱格式不正确 | 检查是否含 @ 与合法域名。 |
NAME_INVALID | 项目名称超过 120 字或含非法字符 | 缩短名称或去掉特殊字符。 |
PASSWORD_INVALID | 密码强度不足（需 10 位以上，含字母与数字） | 使用更强密码。 |
PASSWORD_MISMATCH | 两次输入的密码不一致 | 重新输入并保持两次一致。 |
LOGIN_INVALID | 账号或密码错误 | 检查后重试；连续错误可能触发锁定（H029 规划中）。 |
REQUEST_INVALID | 请求体缺少必需字段或类型不符 | 核对 API 文档中的字段定义。 |
BAD_LIMIT | limit 参数超出范围（1-100） | 调整分页大小。 |
BAD_SORT | 排序字段不被支持 | 使用允许的排序键。 |
401
| 错误码 | 含义 | 怎么处理 |
|---|
AUTH_REQUIRED | 需要登录 | 先完成登录或携带有效会话。 |
TOTP_INVALID | 两步验证（TOTP）动态码错误 | 用验证器 App 重新生成或检查时间同步。 |
403
| 错误码 | 含义 | 怎么处理 |
|---|
ADMIN_REQUIRED | 该操作需要管理员角色 | 联系管理员。 |
EXPORT_QUOTA | 本月整站导出额度已用尽 | 升级会员或下月再试。 |
MEDIA_QUOTA | 素材存储额度已用尽 | 删除未用素材或升级。 |
PAGE_QUOTA | 页面数超出当前等级上限 | 减少页面或升级。 |
PROJECT_QUOTA | 活跃项目数超出当前等级上限 | 归档旧项目或升级。 |
VERSION_LIMIT | 版本保留数量已达上限 | 删除旧版本或升级。 |
SCENE_LIMIT | Motion 场景数已达上限 | 删除未用场景或升级。 |
CSRF_INVALID | CSRF 令牌缺失或已过期 | 刷新页面后重新提交。 |
ORIGIN_DENIED | 请求来源（Origin）不在白名单内 | 确认部署域名与 CORS 设置一致。 |
404
| 错误码 | 含义 | 怎么处理 |
|---|
NOT_FOUND | 资源不存在或已被删除 | 检查 URL 或登录账号是否有权限。 |
405
| 错误码 | 含义 | 怎么处理 |
|---|
METHOD_NOT_ALLOWED | HTTP 方法不被该接口支持 | 使用正确的 GET/POST/PATCH/DELETE。 |
409
| 错误码 | 含义 | 怎么处理 |
|---|
DUPLICATE | 资源已存在（唯一键冲突） | 更换名称或 ID。 |
VERSION_CONFLICT | 你基于旧版本保存，期间已有新版本 | 重新加载最新版本后再编辑，或另存为新项目。 |
ALREADY_OWNED | 该资源已属于你 | 无需重复添加。 |
EMAIL_UNAVAILABLE | 该邮箱已被使用 | 换邮箱或登录原账号。 |
LAST_ADMIN | 不能移除或降权最后一个管理员 | 先提升其他成员为管理员。 |
SELF_PROTECTION | 不能对自己执行该操作（降权/移除） | 找另一位管理员处理。 |
413
| 错误码 | 含义 | 怎么处理 |
|---|
MEDIA_TOO_LARGE | 上传文件超出大小上限 | 压缩后再上传。 |
IMAGE_TOO_LARGE | 图片像素总量超出上限 | 缩小分辨率后重试。 |
415
| 错误码 | 含义 | 怎么处理 |
|---|
JSON_REQUIRED | 该接口只接受 JSON 请求体 | 检查 Content-Type 是否为 application/json。 |
429
| 错误码 | 含义 | 怎么处理 |
|---|
RATE_LIMITED | 请求过频，已被限流 | 稍等片刻再试（通常 1 分钟内恢复）。 |
AI_QUEUE_FULL | AI 任务队列已满 | 稍后再试或减少批量提交。 |
503
| 错误码 | 含义 | 怎么处理 |
|---|
AI_NOT_CONNECTED | 服务端未配置模型密钥 | 联系部署方配置后重试。 |
错误码由服务端统一抛出（AccessError）；此处为面向用户的只读对照，完整字典以 API 文档为准（规划中，见 G029）。