# 错误处理与重试

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

在转换任务失败或耗时较长时，构建稳定且可预期的接入体验。


请把转换结果视为一个有状态的任务，而不是同步的文件下载。这样即使源文件较大、不可访问或格式异常，产品也能保持可靠。

## 安全地重试

只重试可以安全重复的请求。结果查询可以使用指数退避重试。对于提交请求，请先持久化成功响应中的任务 ID，再决定是否需要发起新的提交。

## 处理终态失败

当任务状态为 `failed` 时，请将任务 ID、返回原因和你自己的任务 ID 一同记录。面向用户时，应提供可执行的下一步，例如检查源文件 URL 或上传可读取的 PDF，而不是直接展示未经整理的 API 报错。

## 设置合理的时间上限

轮询截止时间应与产品体验相匹配。达到上限后停止前台轮询，保留任务 ID，并通过后台任务或用户主动刷新在之后查询最终状态。

精确的响应字段和失败示例请查看 [API Reference](https://pdfcraft.ai/zh-CN/api/)。

## 限流与重试

HTTP 429 可能表示请求速率、累计配额或并发数已达上限。响应包含 `Retry-After` 时按其等待；否则使用有截止时间的指数退避。检查 JSON 错误及可选的 reason、retryAfterMs 字段。不要假定存在固定配额，也不要把等待时间当作容量恢复的保证。

网络结果不明确时不要自动重复提交任务。限流器内部使用的请求 ID 不等于公开的客户端幂等键，也不要假定轮询结果与提交任务消耗相同额度。