HTTP 状态码

状态码	error	何时出现
200	—	成功
400	missing_act	榜单接口缺少 act
400	missing_query	搜索接口四个条件全空
400	invalid_price_range	mip 大于 mxp
404	unknown_act	榜单 act 不在白名单
404	unknown_category	分类不存在或未对外开放（如未上线的分类、公告区、我的关注位）
429	rate_limited	超过限流额度
503	source_unavailable / search_unavailable	数据源或搜索服务暂时不可用

错误响应体：

{ "code": 404, "error": "unknown_act", "msg": "未知榜单 act：xxx（可用值见 /api/v1/meta）" }

限流

按 IP + 接口 计数，额度 60 次/分钟。响应头会给出当前状态：

响应头	说明
X-RateLimit-Limit	本窗口总额度
X-RateLimit-Remaining	剩余次数
X-RateLimit-Reset	窗口重置时间（Unix 秒）
Retry-After	仅 429 时出现，建议等待秒数

正确的重试姿势是读 Retry-After 等待对应秒数；不要立即重试，连续触发会被持续限流。

缓存建议

响应 meta.cache_ttl 给出了服务端建议的缓存秒数（榜单 60 秒、分类流 10 秒、搜索 30 秒、能力清单 600 秒）。按该值在客户端缓存即可显著降低请求量与触发限流的概率。各接口具体值以 meta.cache_ttl 为准，不要写死。

本 API 不提供的能力

能力	原因
SSE 实时推送流	长连接会独占服务端进程，不对外开放。需要实时性请以 10 秒间隔轮询 /api/v1/feed
状态投票（仍有效 / 已失效）	写接口，不对外开放
转链跳转接口	活动直达链接已包含在 /api/v1/shenghuo 的 h5 字段中
用户筛选规则	属于登录用户的私有配置，公开接口不适用

最新清单以 /api/v1/meta 的 not_provided 字段为准。