# 错误码

> 错误格式与常见错误码

来源: https://platform.snapany.com/zh/docs/errors

所有错误统一 JSON 结构：

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

## 通用错误码

| HTTP | Code                   | 含义                               | 解决办法                                                                                                 |
| ---- | ---------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------- |
| 400  | _（随场景变化）_       | 业务处理失败                       | 按响应里的 `code` 处理（提取类错误码见下表）——这类调用**不扣费**                                         |
| 401  | `invalid_api_key`      | key 缺失、格式错误或已删除         | 检查 `Authorization: Bearer sk_snapany_xxx` 请求头，并到[控制台 → API Keys](https://platform.snapany.com/zh/console/keys) 确认 key 状态 |
| 402  | `insufficient_credits` | 余额不足                           | 到[控制台](https://platform.snapany.com/zh/console)充值，或开启自动充值                                                                 |
| 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）         | 回退到[转录](https://platform.snapany.com/zh/docs/transcription)          |
| `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 代理下载](https://platform.snapany.com/zh/docs/youtube-proxy-download)：返回同样的结构，并为 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` 字段，预扣的积分自动退回。