| 区间 | 含义 |
|---|
0 | 成功 |
1xxx | 客户端错误（参数 / 资源不存在 / 冲突） |
2xxx | 上游错误（Cloudreve / 百度 4xx-5xx） |
3xxx | 服务内部错误 |
| Cloudreve 透传 | 鉴权失败时直接透传 Cloudreve /user/info 的 code |
| HTTP | envelope.code | ApiError 变体 | 含义 |
|---|
| 200 | 0 | — | 成功 |
| 200 | 1000 | BadRequest(msg) | 参数校验失败 |
| 200 | 1004 | NotFound(msg) | 资源不存在 |
| 200 | 1009 | Conflict(msg) | 唯一约束冲突（重名） |
| 200 | 2000 | Cli(CliError::Remote(...)) | 上游远程错误（Cloudreve / 百度返非 0） |
| 200 | 2004 | Cli(CliError::NotFound(...)) | 上游资源不存在（4xx 但归为“业务“） |
| 200 | 3002 | Cli(CliError::Config(...)) | 配置错误（缺字段 / 非法值） |
| 200 | 3007 | Cli(CliError::Consistency(...)) | 迁移一致性校验失败 |
| 401 | 1000 | Unauthorized(msg) | 头缺失 / 格式错误 / JWT 过期 |
| 401 | 透传 | UpstreamAuth { code, msg } | Cloudreve 端 token 无效 |
| 401 | 2001 | Cli(CliError::Auth(...)) | 百度凭证过期 / 不存在 |
| 403 | 1000 | Forbidden(msg) | 非 admin 访问 /admin/* |
| 500 | 3000 | Internal(msg) | 服务内部 panic / 未分类错误 |
| 500 | 3001 | Cli(CliError::LocalIo(...)) | 本地 IO 失败（写 db / log） |
鉴权失败时 HTTP 401 + envelope.code 透传上游：客户端可以直接拿这个 code 跟 Cloudreve API 文档对照。其余业务错误一律 HTTP 200 + 业务 code 区分。
| code | 客户端应做 |
|---|
0 | 处理 data |
1000 | 提示用户参数错误（看 msg） |
1004 | 提示资源不存在；可能本地缓存过时，刷新列表 |
1009 | 提示重名/冲突，让用户改名重试 |
2000 / 2001 / 2004 | 上游故障，提示“暂时不可用“，按 msg 决定是否重试 |
3000 / 3001 / 3002 | server 端故障，无重试价值；上报 request_id 给管理员 |
3007 | 一致性校验失败，提示用户检查源 / 目标差异；可调 migrate retry 重试 |
| HTTP 401 | 让用户重新登录 Cloudreve 拿新 token |
| HTTP 403 | 非 admin 路径不要展示 admin 功能 |
migrate_task 表有个 last_err 字段，记录最近一次失败的错误信息（人类可读字符串）。任务失败状态（failed / verify_failed）下通过 GET /migrate/jobs/{job_id}/tasks 或 GET /admin/users/{user_id}/migrate 可以看到。