API 错误码：18 个提取错误码与重试判断

错误格式

所有非 200 的响应体都是同一种 JSON 结构：

{
  "message": "该内容已被删除或不存在",
  "code": "content_deleted",
  "retryable": false
}

字段	说明
`message`	给人看的说明，语言由 `Accept-Language` 请求头决定。不要拿它做逻辑判断，措辞会调整。
`code`	机器可读的错误码。提取失败的 `400` 一定带，`429` 固定为 `too_many_requests`；`401`、`402`、`422`、`500` 不带，用状态码本身判别。请求体不是合法 JSON 时只有 `message`。
`retryable`	同一链接稍后重试是否可能成功，随 `code` 一起出现
`detail`	仅 `422` 有，是请求体校验问题的列表

HTTP 状态码

状态码	含义	常见原因	处理
`200`	成功	-	响应体即提取结果，此时才扣费
`400`	提取失败	链接无效、内容不可访问、平台限制等；请求体不是合法 JSON 也是 `400`，但只带 `message`	按 `code` 处理，见下表。不扣费。
`401`	鉴权失败	缺 `Authorization` 请求头或不是 `Bearer` 方案、API Key 错误或已重置	到开发者管理中心核对 Key
`402`	额度用尽	剩余次数为 0	到开发者管理中心充值
`422`	请求体不合法	缺 `url`、`url` 不是字符串、`Content-Type` 不是 JSON（此时请求体按空对象校验）	看 `detail`，修正请求
`429`	触发限流	超过每个 Key 每分钟 1200 次，`code` 为 `too_many_requests`	退避后重试。MCP 与 REST 共用这份配额。
`500`	服务器错误	服务内部异常	稍后重试，持续出现请联系我们

提取错误码

提取失败返回 HTTP 400，code 取自下面 18 个值之一。这些都是业务失败，不扣费。

code	含义	常见原因	怎么办	`retryable`
`invalid_url`	链接格式不对	传的不是 URL，或没有可识别的链接	修正 URL	`false`
`unsupported_url`	不是帖子 / 视频链接	URL 合法但不是内容页，如站点首页、搜索页	换用单个帖子或视频的分享链接	`false`
`unsupported_site`	该站点暂不支持	平台不在支持列表	联系我们提需求	`false`
`invalid_playlist_url`	不是主页 / 频道 / 播放列表链接	主页批量接口收到了单帖链接或非列表页	换用公开的作者主页、频道或播放列表 URL	`false`
`playlist_not_supported`	把列表链接传给了单帖接口	`/extract/post` 收到了主页 / 播放列表链接	改调 `/extract/playlist`，或传单个帖子链接	`false`
`content_deleted`	内容已删除或不存在	帖子被删、链接错误、从未存在	无内容可提取	`false`
`user_not_found`	找不到该用户	账号已注销、改名或被平台限制	核对用户名	`false`
`no_story`	该账号当前没有可看的快拍	快拍 24 小时后消失	稍后有新快拍时再试	`false`
`private_content`	私密内容	私密账号或仅关注者可见	无法提取	`false`
`members_only_content`	付费或会员专享内容	需要订阅、付费或会员身份	无法提取	`false`
`age_restricted`	年龄限制	平台要求登录验证年龄	无法提取（见下方说明）	`false`
`region_restricted`	地区限制	内容仅特定地区可见	无法提取（见下方说明）	`false`
`not_premiered`	内容尚未发布	预约首映 / 定时发布尚未到时间	到点后再试	`false`
`live_stream_not_supported`	该站点的直播暂不支持	直播进行中	等直播转为回放后再试（见下方说明）	`false`
`extract_failed`	提取失败	站点改版，或该内容当前无法正常访问	稍后重试	`true`
`retryable`	临时失败	提取过程中的瞬时错误	稍等片刻后重试	`true`
`timeout`	提取超时	本次提取耗时超出限制	稍等片刻后重试	`true`
`unknown`	未归类的失败	未预期的错误	先重试一次，反复出现请带上请求时间联系我们	`true`

age_restricted、region_restricted、live_stream_not_supported 这三个码只在少数平台上出现。年龄限制、地区限制的资源我们大多能正常提取，直播也支持很多平台（如 Twitch、TikTok）。收到这三个码只说明这个平台的这类资源当前拿不到，不代表不支持这类资源。

retryable 的语义

retryable 是对「同一个链接稍后重试有没有意义」的回答，和错误码一起下发：

true：临时性失败，同一链接过一会儿重试有可能成功。建议指数退避，从几秒开始，重试两三次仍失败就放弃并记录。
false：关于内容本身的确定性结论（已删除、私密、不支持……），重试多少次结果都一样，不要重试
没有这个字段：按 false 处理

错误码会随时间新增。遇到不在上表里的 code，按永久失败处理并记录日志，不要循环重试。同一个平台持续返回 extract_failed、或 unknown 反复出现，请带上请求时间联系我们。

retryable 表示的是「可以重试」，不是「一定会成功」；表格里的值是各错误码的典型值，请以响应里实际下发的为准。