这一页讲开放 API出错时怎么看、被限流了怎么办。怎么用：先按 HTTP 状态码和 error 字段对号入座，再按「限流」一节的等待建议重试。

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 秒、生活优惠 60 秒、能力清单 600 秒）。按该值在客户端缓存即可显著降低请求量与触发限流的概率。各接口具体值以 meta.cache_ttl 为准，不要写死。

本 API 不提供的能力

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

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

常见问题

Q：60 次/分钟是所有接口加起来算吗？
不是。按“IP + 接口”分桶，rank、feed、search、meta、shenghuo 各自独立计数：一分钟内把 rank 打到 60 次，不影响你继续调 feed；换一个出口 IP 则是另一份额度。

Q：收到 503 该重试吗？
可以，但要间隔几秒并做退避；这是搜索服务或数据源临时不可用，不是参数错。连续失败建议先看 /api/v1/meta 是否正常。

Q：为什么 429 响应里 code 也是 429？
错误响应的 code 等于 HTTP 状态码，error 才是机器可读错误码（这里是 rate_limited）。判断逻辑请优先看 error。