错误码
所有错误统一 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 | 常见原因 | 怎么办 |
|---|---|---|
InvalidURL | 不是受支持的帖子链接 | 确认 URL 是指向单个帖子的直链 |
ContentDeleted | 帖子已被平台删除 | 无内容可提取 |
PrivateContent | 需登录可见或私密内容 | 无法提取 |
ExtractFailed | 平台改版或上游临时故障 | 稍后重试；同一站点持续失败请联系我们 |
转录失败
轮询时失败任务返回 "status": "failed" 和 error 字段，预扣的积分自动退回。