# 错误码

## 响应结构

```json
{ "code": 404, "msg": "文件不存在" }
```

- `code` 与 HTTP 状态码一致；失败时无 `data` 字段。
- `msg` 为中文可读信息，可直接展示给用户。

## 业务状态码

| 状态码 | 语义 | 典型场景 |
|---|---|---|
| 200 | 成功 | 全部正常响应 |
| 400 | 参数/格式错误 | 缺字段、过期策略非法、时间格式错误、分片哈希不匹配、code 冲突、`chunk_size` 超 32MiB 上限、presign 实际大小与声明不符、请求体超过大小上限 |
| 401 | 未认证 | 管理端令牌缺失/无效；登录密码错误 |
| 403 | 拒绝 | 类型白名单拒绝、magic bytes 防伪、游客上传未开启、**分片上传未启用**（enableChunk=0）、presign 直传对象超限（服务端删除对象并释放预留）、下载 `key` 鉴权失败、超过大小/时长限制 |
| 404 | 不存在/已过期 | 取件码不存在、文件已过期、上传会话不存在、`/api/*` 未命中路由 |
| 409 | 冲突 | 上传容量预留信息不一致 |
| 416 | Range 越界 | `Range: bytes=…` 超出文件大小 |
| 423 | 限流 | upload/error/login/metadata 任一规则超限 |
| 428 | 未初始化 | 系统未初始化时访问除 `/setup`、`/api/v1/health` 外的接口 |
| 500 | 服务器错误 | 数据库/内部异常 |
| 501 | 引擎不支持 | 引擎不支持预签名等操作（local/webdav 的 `PresignGetURL/PutURL`） |
| 503 | 存储不可用 | 存储引擎连接失败/健康检查不通过时的操作 |
| 507 | 容量超限 | 达到 `storageLimit` 上限（含上传预留判定） |

## 存储哨兵错误映射

存储层哨兵错误统一映射（支持错误包装链判定）：

| 哨兵错误 | HTTP | 响应 msg |
|---|---|---|
| `ErrNotFound` | 404 | 文件不存在 |
| `ErrInvalidPath` | 400 | 非法文件路径 |
| `ErrUnavailable` | 503 | 存储服务不可用，请稍后再试 |
| `ErrNotSupported` | 501 | 当前存储引擎不支持该操作 |
| `ErrRangeNotSatisfiable` | 416 | 请求范围超出文件大小 |
| `ErrHashMismatch` | 400 | 分片哈希校验失败，请重新上传 |

未识别的存储错误归入 500（`存储操作失败: …`）。

## 错误结果的审计归类

错误响应同时写入审计日志（需求 ③）：

- `denied`：401 / 403 / 423 / 429 / 428（拒绝类）。
- `failed`：其余 4xx / 5xx 及业务显式报错。

## 常见排障

| 现象 | 原因与处理 |
|---|---|
| 全部接口 428 | 未初始化：访问 `GET /setup` 或 `POST /setup` 完成向导 |
| 上传 403「本站未开启游客上传」 | `openUpload=0`，携带管理员 Bearer 令牌或后台开启 |
| 上传 423 | 触发 upload 限流，等待窗口或调大 `uploadCount/uploadMinute` |
| 取件 404「文件已过期」 | 分享过期/次数耗尽；管理员可 `PATCH /admin/file/update` 调整 |
| 下载 403「下载鉴权失败」 | `key` 窗口令牌过期/伪造：重新 `POST /share/select` 获取新地址 |
| 预签名 init 返回 proxy | local/webdav 引擎不支持直链，按 proxy 流程走服务端代理上传 |
| 503 存储服务不可用 | 检查引擎配置与远端服务（S3/WebDAV）连通性；`GET /api/v1/health` 的 `storage` 字段确认引擎 |