# 错误处理指南

发生错误时，应诊断并采取行动 — 永远不要直接向用户展示原始错误信息。

## API 错误码

| 错误码 | 含义 | 处理方式 |
|------|---------|--------|
| `4100` | 积分不足 | 告知用户余额不足。显示当前余额，建议到[特看视频](https://video.tekan.cn/subscription?action=recharge)充值。 |
| `4007` | 存在未完成的任务 | 上一个任务仍在运行。等待 30 秒后重试，或询问用户是否要取消上一个任务。 |
| `4000` / `4001` / `4003` | 参数错误 | 检查模型支持的参数（宽高比、分辨率、时长）。修正后重试。 |
| `5003` | 服务器繁忙 | 等待 10-30 秒后重试。如果持续出现，建议尝试其他模型。 |
| `5000` / `5001` | 内部服务器错误 | 重试一次。如果持续出现，建议用户稍后再试或使用网页端。 |
| `6001` | 安全问题 | 内容可能触发了安全过滤器。建议修改提示词。 |

## 任务级失败

| 情况 | 处理方式 |
|-----------|--------|
| 任务 `status: fail` | 读取 `errorMsg`。常见原因：模型服务不可用（尝试其他模型）、内容策略违规（修改提示词）。 |
| 任务超时（退出码 2） | 任务可能仍在运行。使用 `query --task-id <id> --timeout 1200` 恢复轮询。不要重新提交 — 那会浪费积分。 |
| 部分成功（`generatingCount > 1`） | 部分子任务可能失败而其他成功。检查每个视频的 `status`。仅对失败的重试。 |
| 上传失败 | 检查文件格式（必须是 png/jpg/jpeg/bmp/webp/mp3/wav/m4a/mp4/avi/mov）和文件大小。重试一次。 |

## 恢复决策树

```
发生错误
├─ API 错误码？
│  ├─ 4100 → 告知用户：积分不足
│  ├─ 4007 → 等待后重试
│  ├─ 400x → 修正参数，重试
│  └─ 500x → 重试一次，然后建议稍后再试
├─ 任务状态 = fail？
│  ├─ "Model service unavailable" → 尝试其他模型
│  ├─ 内容策略违规 → 修改提示词
│  └─ 未知原因 → 使用相同参数重试一次
└─ 超时？
   → 使用 `query --task-id <id>` 恢复轮询（不要重新提交）
```