请把转换结果视为一个有状态的任务,而不是同步的文件下载。这样即使源文件较大、不可访问或格式异常,产品也能保持可靠。
安全地重试
只重试可以安全重复的请求。结果查询可以使用指数退避重试。对于提交请求,请先持久化成功响应中的任务 ID,再决定是否需要发起新的提交。
处理终态失败
当任务状态为 failed 时,请将任务 ID、返回原因和你自己的任务 ID 一同记录。面向用户时,应提供可执行的下一步,例如检查源文件 URL 或上传可读取的 PDF,而不是直接展示未经整理的 API 报错。
设置合理的时间上限
轮询截止时间应与产品体验相匹配。达到上限后停止前台轮询,保留任务 ID,并通过后台任务或用户主动刷新在之后查询最终状态。
精确的响应字段和失败示例请查看 API Reference。