# 错误码

> 错误格式与常见错误码

来源: 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             | 常见原因               | 怎么办                               |
| ---------------- | ---------------------- | ------------------------------------ |
| `InvalidURL`     | 不是受支持的帖子链接   | 确认 URL 是指向单个帖子的直链        |
| `ContentDeleted` | 帖子已被平台删除       | 无内容可提取                         |
| `PrivateContent` | 需登录可见或私密内容   | 无法提取                             |
| `ExtractFailed`  | 平台改版或上游临时故障 | 稍后重试；同一站点持续失败请联系我们 |

## 转录失败

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