82581d2949
Add TMDB search and media detail pages, HDHive resource ingestion flow, unified error handling, Docker single-container runtime, and project docs/config updates for local deployment. Co-authored-by: Cursor <cursoragent@cursor.com>
64 lines
1.7 KiB
Markdown
64 lines
1.7 KiB
Markdown
# 通用响应格式
|
|
|
|
所有 OpenAPI 接口均采用统一 JSON 响应结构。
|
|
|
|
## 成功响应
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"code": "200",
|
|
"message": "success",
|
|
"data": { "...": "..." },
|
|
"meta": { "...": "..." }
|
|
}
|
|
```
|
|
|
|
| 字段 | 类型 | 说明 |
|
|
|---|---|---|
|
|
| `success` | boolean | 是否成功 |
|
|
| `code` | string | 状态码或业务码 |
|
|
| `message` | string | 响应消息 |
|
|
| `data` | object / array / null | 响应数据 |
|
|
| `meta` | object / null | 分页、统计等元信息 |
|
|
|
|
## 错误响应
|
|
|
|
```json
|
|
{
|
|
"success": false,
|
|
"code": "ERROR_CODE",
|
|
"message": "Error message",
|
|
"description": "详细错误描述",
|
|
"limit_scope": "app",
|
|
"limit_scope_label": "应用",
|
|
"retry_after_seconds": 300
|
|
}
|
|
```
|
|
|
|
| 字段 | 类型 | 说明 |
|
|
|---|---|---|
|
|
| `success` | boolean | 固定为 `false` |
|
|
| `code` | string | 错误码 |
|
|
| `message` | string | 错误消息 |
|
|
| `description` | string | 面向用户或开发者的中文说明 |
|
|
| `limit_scope` | string / undefined | 限制类错误的对象，可能为 `app` 或 `user` |
|
|
| `limit_scope_label` | string / undefined | 限制对象中文说明 |
|
|
| `retry_after_seconds` | integer / undefined | 建议等待秒数 |
|
|
|
|
## 业务错误码
|
|
|
|
| 错误码 | HTTP 状态码 | 说明 |
|
|
|---|---|---|
|
|
| `400` | 400 | 请求参数错误 |
|
|
| `401` | 401 | 未授权 |
|
|
| `403` | 403 | 无权访问 |
|
|
| `404` | 404 | 资源不存在 |
|
|
| `500` | 500 | 服务内部错误 |
|
|
| `INSUFFICIENT_POINTS` | 402 | 积分不足 |
|
|
| `VIP_REQUIRED` | 403 | 需要 Premium |
|
|
| `SCOPE_NOT_ALLOWED` | 403 | 应用 scope 不足 |
|
|
| `USER_SCOPE_NOT_ALLOWED` | 403 | 用户授权 scope 不足 |
|
|
| `OPENAPI_USER_REQUIRED` | 403 | 缺少用户身份 |
|
|
| `RATE_LIMIT_EXCEEDED` | 429 | 请求触发限制，应按 `Retry-After` 退避 |
|