错误码

所有错误统一 JSON 结构：

{ "message": "人类可读的错误信息", "code": "机器可读错误码", "detail": "可选详情" }

通用错误码

HTTP	Code	含义	解决办法
400	（随场景变化）	业务处理失败	按响应里的 `code` 处理（提取类错误码见下表）——这类调用不扣费
401	`invalid_api_key`	key 缺失、格式错误或已删除	检查 `Authorization: Bearer sk_snapany_xxx` 请求头，并到控制台 → API Keys 确认 key 状态
402	`insufficient_credits`	余额不足	到控制台充值，或开启自动充值
404	—	资源不存在（如转录任务 `id` 无效）	核对接口返回的资源 `id`
422	—	请求参数错误	`detail` 字段会说明哪个参数错、错在哪
429	`rate_limited`	超过 1200 次/分钟	退避后延迟重试
500	—	服务器错误	稍后重试；持续出现请联系我们

提取错误码

提取失败返回 HTTP 400 并带提取引擎的错误码。这些是业务失败——不扣费。

Code	常见原因	怎么办
`invalid_url`	链接格式不对	修正 URL 格式
`unsupported_url`	URL 合法，但不是帖子/视频链接	换用单个帖子或视频的分享链接
`unsupported_site`	该站点暂不支持，或该接口不支持此站点	核对该接口支持的站点，或联系我们提需求
`no_subtitles`	视频没有字幕轨道（HTTP 404）	回退到转录
`invalid_playlist_url`	不是频道/主页/播放列表链接	换用公开的频道、主页或播放列表 URL
`playlist_not_supported`	把列表链接传给了单帖接口	改调 `/extract/playlist`，或传单个帖子链接
`content_deleted`	内容已删除或从未存在	无内容可提取
`user_not_found`	账号已注销、改名或被平台限制	核对用户名
`no_story`	该账号当前没有可看的快拍	快拍 24 小时后消失
`private_content`	私密内容或仅关注者可见	无法提取
`members_only_content`	付费或会员专享内容	无法提取
`age_restricted`	该资源存在年龄限制	无法提取（见下方说明）
`region_restricted`	该资源存在地区限制	无法提取（见下方说明）
`not_premiered`	预约内容尚未开播	到点后再试
`live_stream_not_supported`	该站点的直播暂不支持提取	等直播转为回放后再试（见下方说明）
`extract_failed`	站点改版，或该内容当前无法正常访问	稍后重试（见下方说明）
`retryable`	提取过程临时失败	稍等片刻后重试（见下方说明）
`timeout`	提取超时	稍等片刻后重试（见下方说明）
`unknown`	未归类的失败	先重试一次（见下方说明）

extract_failed、retryable、timeout、unknown 这四个是临时性失败，同一个链接稍后重试有可能成功。其余错误码都是关于内容本身的确定性结论，重试多少次结果都一样。错误码会随时间新增，遇到不认识的码请按永久失败处理并记录日志，不要反复重试。同一个站点持续返回 extract_failed、或 unknown 反复出现，请带上请求时间联系我们。

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

下载 YouTube 媒体时报 403 Forbidden

这个 403 不是 SnapAny API 返回的：提取已经成功，但从你自己的服务器下载返回的 YouTube video_url / audio_url / resource_url 时失败。YouTube 常拒绝来自机房 IP（云服务器、VPS）的下载，部分链接还只允许美国 IP 下载——带上媒体的 headers 也无济于事。

改用 YouTube 代理下载：返回同样的结构，并为 1080p 及以下的档位附上代理链接，下载经由我们的网络转发，不直连 YouTube。代理链接返回 404（payload_expired）时重新调用接口；返回 403（upstream_error）的情况很少见，重试一次通常就能成功，仍失败再重新调用接口。

转录请求错误

这些错误在提交接口就返回（HTTP 400），任务尚未创建，不扣费。

Code	常见原因
`file_too_large`	上传超过 512 MB，或 `file_url` 指向的文件超限
`audio_too_long`	音频时长超过 6 小时
`unsupported_audio_format`	音频格式不在支持列表，或时长解析不出来
`download_failed`	我们无法从 `file_url` 取到文件
`unsupported_language`	`language` 不在上游支持的语种列表内；省略该字段即自动检测，或传语种名 / ISO 代码（`english`、`en`、`chinese`、`zh`）

转录失败

轮询时失败任务返回 "status": "failed" 和 error 字段，预扣的积分自动退回。