错误与重试

错误码说明及对应的处理方法。

HTTP 请求成功不等于转换成功。查询任务可能返回 200，但任务状态是 failed。先检查 HTTP 状态，再检查任务状态及 error.code。

API 请求错误

API 错误通常返回以下 JSON 结构。鉴权失败或文件上传、下载失败时，也可能收到其他格式的响应。

json

{  "error": {    "code": "SOURCE_FILE_MISSING",    "message": "source file must be uploaded before launch"  }}

HTTP / 错误码	处理方法
`400 INVALID_REQUEST`	检查字段名、语言代码、格式组合和查询参数；修正后再重试
`401`	检查 API Key 与环境，更换无效凭据
`404`	检查账户与任务 ID，任务可能已经过期；成功前请求结果下载也会返回 404
`409 SOURCE_FILE_MISSING`	上传原文件，再启动同一任务
`409 TRANSFORM_CONCURRENCY_LIMIT`	等待运行名额，在任务过期前重试启动
`409 TRANSFORM_ALREADY_LAUNCHED`	使用原参数；确实需要另一种转换时才创建新任务
`429`、`502`、`503`、`504`	查询请求可逐渐延长间隔重试，并设置重试上限；有 `Retry-After` 时按其等待。写入请求先确认是否已被接受

程序应根据 error.code 判断错误类型，error.message 仅供阅读。遇到未知错误码时，请记录下来，便于排查。

响应中可能没有限流提示，仍需处理 429。

状态为 failed 时，通过 GET /transforms/{uuid} 查看错误详情，完成列表中也会返回该错误。

`error.code`	恢复方法
`INVALID_SOURCE_FILE`	修复或重新导出 PDF/EPUB，再建任务并上传修正后的文件
`BALANCE_EXHAUSTED`	检查并补充账户余额后，再提交新任务
`INVALID_ARTIFACT`	保留任务 ID 并联系支持，重复上传同一文件不一定能解决
`INTERNAL_ERROR` 或未知错误码	记录任务 ID、时间和错误码以便排查，不要循环自动创建任务

失败任务无法通过再次调用 launch 重启。如需重试，应创建新任务，可能会再次产生处理费用。失败前生成的预览只包含部分内容。

如果没有收到创建响应，请先检查等待上传列表，确认任务是否已经创建。上传中断后，重新获取上传地址即可确认文件是否已经上传。没有收到启动响应时，可以查询任务状态，或用原参数重试 launch。

上传或下载链接过期后，可以通过 API 重新获取。上传使用 PUT，并带上接口返回的请求头；下载使用 get_url，查看文件信息的 HEAD 请求使用 head_url。这些文件请求都无需传入 API Key。恢复步骤见任务生命周期与恢复。

联系 support@oomol.com 时，请提供任务 uuid、大致请求时间、HTTP 状态及 error.code，不要发送 API Key 或存储签名 URL。