media_crawler/docs/hdhive-openapi-docs/limits.md

限制与错误处理

限制维度

OpenAPI 会按多个维度保护系统稳定性：

• 应用级限制：按 API Key / OpenAPI 应用维度限制请求频率和突发流量。
• 用户级限制：按实际调用用户维度限制请求频率和每日成功业务请求。
• 接口组限制：按 meta/query/write/unlock/vip 分组控制访问频率和是否计量。
• IP 策略：支持不限制 IP、固定 IP 白名单、动态 IP 风控。
• unlock 风控：资源解锁接口保留旧的用户阶梯处罚监测，处罚对象是实际授权用户，不是整个第三方应用。

具体阈值由管理员配置，不在开发者文档中公开。接入方只需要按响应头和错误码处理退避。

429 处理规则

当请求返回 429 时，客户端应读取 Retry-After 头，并在等待后重试。不要在冷却期内持续重试。

HTTP/1.1 429 Too Many Requests
Retry-After: 300

429 错误响应会通过 limit_scope 明确说明限制对象：

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