# 任务生命周期与恢复

[HTML](https://pdfcraft.ai/zh-CN/docs/api/lifecycle/) · [Site index](https://pdfcraft.ai/llms.txt)

任务状态、并发限制、过期时间和中断恢复。


创建任务后，请保存返回的 `uuid` 和启动时使用的参数。恢复任务时需要用到这些信息。上传和下载链接会过期，不能代替任务 ID。

## 状态

```text
waiting_for_upload → running → succeeded | failed | cancelled
```

| 状态 | 含义 | 下一步 |
| --- | --- | --- |
| `waiting_for_upload` | 已创建、尚未启动，文件可能已经上传 | 获取上传地址，按需上传，再启动 |
| `running` | 已接受启动请求，可能仍在排队 | 逐渐延长轮询间隔 |
| `succeeded` | 任务仍可访问时，结果可以下载 | 获取下载链接 |
| `failed` | 处理失败 | 读取任务的 `error.code` |
| `cancelled` | 任务已取消 | 停止轮询 |

目前 API 不提供取消或删除任务的接口。

## 请求中断后恢复

| 中断操作 | 处理方法 |
| --- | --- |
| 创建，未确认 `uuid` | 检查等待上传列表，确认后再决定是否重新创建 |
| 上传 | 重新获取上传地址；返回 `get_url` 和 `head_url` 表示文件已上传，返回 `put_url` 则需要上传 |
| 启动 | 查询任务状态，必要时用原参数重试 launch |
| 轮询 | 保留 `uuid`，稍后继续查询 |
| 下载 | 任务仍可访问时，重新获取下载链接 |

如果要更换已上传的文件，需要创建新任务。

服务接受启动请求后，会保存规范化后的参数。重复提交相同参数只会返回已有任务，不会再次执行，即使任务已经失败。更换参数则返回 `409 TRANSFORM_ALREADY_LAUNCHED`。

## 同时执行的转换

每个用户最多有 **3 个 `running` 任务**，PDF 与 EPUB 合并计算。启动已接受但仍在等待执行的任务也占名额。创建和文件上传不占名额。

收到 `409 TRANSFORM_CONCURRENCY_LIMIT` 时，任务尚未启动，仍为 `waiting_for_upload`。已上传的文件会保留，过期时间也不变。

可以隔一段时间查询运行列表，等其他任务结束后重试 launch，无需创建新任务。重试前请确认当前任务尚未过期。

## 列表与分页

程序重启或重新登录后，可以通过[列表接口](https://pdfcraft.ai/zh-CN/docs/api/overview/#查询任务列表)找回任务。等待上传列表也包含已经上传但尚未启动的任务；运行列表包含排队任务；完成列表包含成功、失败和已取消任务。

任务记录在 `transforms` 中。有下一页时，响应还会包含 `next_cursor`，将其原样传给同一列表的 `cursor` 参数即可。

列表会随任务状态更新，翻页时任务可能已经转移到另一列表。接口不返回总条数。

## 保留与过期

任务的过期时间由服务决定，以响应中的 `expires_at` 为准。文档示例中的时间仅供说明。

服务接受启动请求后，会清除上传期限；因并发限制而未能启动时，原期限仍然有效。最近完成的任务可能暂时没有 `expires_at`，之后会随保留策略的执行而设置。

查询任务不会延长保留时间。任务一旦过期，查询就会返回 `404`，列表中也不再显示，无需等到文件实际清理。

即使暂时没有 `expires_at`，也请及时下载并保存结果。

## 处理失败

任务失败后，通过 `GET /transforms/{uuid}` 查看 `error.code` 和 `error.message`。observation 不返回错误详情。如何处理各类错误，见[错误与重试](https://pdfcraft.ai/zh-CN/docs/api/error-handling/)；解决问题后再创建新任务。