# 限制与错误处理

## 限制维度

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` 类接口用于健康检查、配额和用量查询，通常不计入用户每日业务额度。非成功响应会回滚本次已预占的每日额度。