HTTP 状态码

状态码	error	何时出现
200	—	成功
400	missing_act / missing_id / invalid_time_range	缺榜单类型或文章 ID，或列表 since 大于 until
400	invalid_category	articles/search 显式传入空分类参数
400	invalid_price_range	mip 大于 mxp
404	unknown_act	榜单 act 不在白名单
413	content_too_large	文章详情原始正文超过 8 MiB，或展示态 HTML 超过 4 MiB
404	article_not_found	文章不存在、不是普通文章或尚未公开
404	unknown_category	分类不存在或未对外开放（feed、search、articles）
429	rate_limited	超过限流额度
503	source_unavailable / search_unavailable / rate_limit_unavailable	文章或其他数据源、搜索服务、限流计数服务暂不可用

错误响应使用 HTTP 状态码，并返回 {"code":404,"error":"unknown_act","msg":"..."}；错误体不含成功响应的 data/meta。成功响应统一为 code/msg/data/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 秒、搜索 30 秒、生活优惠 60 秒、能力清单 600 秒。以各响应实时返回值为准。

本 API 不提供的能力

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

本 API 不提供长连接、状态投票或用户私有筛选规则。最新清单以 /api/v1/meta 的 not_provided 字段为准。