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>
79 lines
3.4 KiB
Markdown
79 lines
3.4 KiB
Markdown
# 限制与错误处理
|
|
|
|
## 限制维度
|
|
|
|
OpenAPI 会按多个维度保护系统稳定性：
|
|
|
|
- **应用级限制**：按 API Key / OpenAPI 应用维度限制请求频率和突发流量。
|
|
- **用户级限制**：按实际调用用户维度限制请求频率和每日成功业务请求。
|
|
- **接口组限制**：按 `meta/query/write/unlock/vip` 分组控制访问频率和是否计量。
|
|
- **IP 策略**：支持不限制 IP、固定 IP 白名单、动态 IP 风控。
|
|
- **unlock 风控**：资源解锁接口保留旧的用户阶梯处罚监测，处罚对象是实际授权用户，不是整个第三方应用。
|
|
|
|
具体阈值由管理员配置，不在开发者文档中公开。接入方只需要按响应头和错误码处理退避。
|
|
|
|
## 429 处理规则
|
|
|
|
当请求返回 `429` 时，客户端应读取 `Retry-After` 头，并在等待后重试。不要在冷却期内持续重试。
|
|
|
|
```http
|
|
HTTP/1.1 429 Too Many Requests
|
|
Retry-After: 300
|
|
```
|
|
|
|
429 错误响应会通过 `limit_scope` 明确说明限制对象：
|
|
|
|
```json
|
|
{
|
|
"success": false,
|
|
"code": "USER_RATE_LIMIT_EXCEEDED",
|
|
"message": "User OpenAPI rate limit exceeded",
|
|
"description": "用户 OpenAPI 请求频率过高，当前授权用户已进入冷却，请稍后重试",
|
|
"limit_scope": "user",
|
|
"limit_scope_label": "授权用户",
|
|
"retry_after_seconds": 300
|
|
}
|
|
```
|
|
|
|
`limit_scope=app` 表示当前应用或 API Key 被限制，所有使用该应用的请求都应退避；`limit_scope=user` 表示当前授权用户被限制，不代表整个第三方应用不可用。
|
|
|
|
## 常见限制错误码
|
|
|
|
| 错误码 | HTTP 状态码 | 说明 |
|
|
|---|---|---|
|
|
| `OPENAPI_COOLDOWN` | 429 | 应用或用户处于 OpenAPI 冷却期，具体对象读取 `limit_scope` |
|
|
| `IP_COUNT_EXCEEDED` | 429 | 动态 IP 风控触发 |
|
|
| `IP_NOT_ALLOWED` | 403 | 请求 IP 不在白名单内 |
|
|
| `APP_RATE_LIMIT_EXCEEDED` | 429 | 应用请求频率过高 |
|
|
| `APP_BURST_LIMIT_EXCEEDED` | 429 | 应用突发请求过高 |
|
|
| `APP_IP_RATE_LIMIT_EXCEEDED` | 429 | 应用单 IP 请求频率过高 |
|
|
| `ENDPOINT_GROUP_RATE_LIMIT_EXCEEDED` | 429 | 接口组请求频率过高 |
|
|
| `USER_RATE_LIMIT_EXCEEDED` | 429 | 用户 OpenAPI 请求频率过高 |
|
|
| `APP_DAILY_QUOTA_EXCEEDED` | 429 | 应用今日成功业务请求额度耗尽 |
|
|
| `USER_DAILY_QUOTA_EXCEEDED` | 429 | 用户今日成功业务请求额度耗尽 |
|
|
| `RATE_LIMIT_EXCEEDED` | 429 | unlock 用户阶梯风控触发 |
|
|
|
|
## 配额响应头
|
|
|
|
部分响应会返回当前用户或应用的剩余信息。客户端可以展示这些信息，但不能假设阈值固定不变。
|
|
|
|
| Header | 说明 |
|
|
|---|---|
|
|
| `Retry-After` | 建议等待秒数 |
|
|
| `X-OpenAPI-User-Daily-Limit` | 用户当日额度上限，存在时返回 |
|
|
| `X-OpenAPI-User-Daily-Remaining` | 用户当日剩余额度，存在时返回 |
|
|
| `X-OpenAPI-App-Daily-Limit` | 应用当日额度上限，存在时返回 |
|
|
| `X-OpenAPI-App-Daily-Remaining` | 应用当日剩余额度，存在时返回 |
|
|
|
|
## 限制字段
|
|
|
|
| 字段 | 类型 | 说明 |
|
|
|---|---|---|
|
|
| `limit_scope` | string | 限制对象，`app` 表示应用，`user` 表示授权用户 |
|
|
| `limit_scope_label` | string | 限制对象中文说明 |
|
|
| `retry_after_seconds` | integer | 建议等待秒数，与 `Retry-After` Header 对齐 |
|
|
|
|
## 计量说明
|
|
|
|
`meta` 类接口用于健康检查、配额和用量查询，通常不计入用户每日业务额度。非成功响应会回滚本次已预占的每日额度。
|