同步还是异步？为链接解析选择合适的调用方式

先决定解析期间，应用应该做什么

用户在审核页面提交一个链接时，你的服务端或许可以等待，然后向本次交互返回结果或明确错误。导入队列则通常需要先保存任务，让其他工作继续，而不要求用户一直停留在页面上。

同步与异步提交使用相同的解析请求体，都需要稳定的 Idempotency-Key，也沿用相同的账户任务和计费规则。把等待放在一次 HTTP 调用里，不会让原本无法访问的来源变得可用，也仍然需要处理解析失败。

一次等待可以完成的交互，使用同步调用

POST /v1/api/jobs/sync 会等待可用结果。成功时返回 HTTP 200，结构与单任务查询的详情一致，响应中的任务标识字段为 id。解析失败时返回明确错误，而不是在成功响应中交给你一个尚未完成的任务。

服务端从受理后统一等待 30 秒，包含首次状态快照和详情读取。HTTP 客户端和网关还要为提交、响应传输以及取消清理预留时间；文档中的 cURL 示例设为 60 秒超时。同步接口不接受用来修改等待时长的查询参数。

每个 API 进程有 64 个同步等待名额。名额占满时，HTTP 429 / SYNC_CAPACITY_EXCEEDED 会在创建任务前拒绝本次请求。请遵守 Retry-After；如果大量交互都需要等待，可以考虑异步提交。账户请求频率和任务并发限制仍然生效。

让异步任务独立执行，再一起查询结果

POST /v1/api/jobs 在受理任务后返回 HTTP 202。把 job_id 保存到自己的业务记录，稍后再查询。这适合后台导入、定时处理，以及用户可以在解析结束前离开的页面。

POST /v1/api/jobs/batch 一次读取 1–100 个已有任务 ID。返回条目与输入顺序一致，重复 ID 也会保留。每项各自包含 http_status、job 和 error，因此一个不存在的 ID 不会遮蔽其他任务的结果。某项 http_status 为 200 表示详情读取成功，解析是否成功还要检查 job.status。

完整未压缩批量 JSON 响应最多为 16 MiB。即使不到 100 个任务，大结果也可能超过预算，重复 ID 的每次输出都会计入体积。遇到 HTTP 422 / BATCH_RESPONSE_TOO_LARGE，应减少 ID 数量或拆批。批量查询只读取已有任务，不会再提交一轮解析。

• 维护尚未结束的任务 ID 集合，按有上限的间隔查询。
• 任务进入终态后移出轮询集合，逐项处理返回的错误。
• 设置退避并遵守 Retry-After；批量查询不会取消账户请求限额。

分清服务端确认取消与客户端没收到响应

收到 HTTP 504 / SYNC_TIMEOUT，表示服务端等待到期，任务已取消，冻结积分已释放且不消费。复用这个任务的请求键仍会指向已取消任务；确实需要重新解析时，使用新的请求键。如果任务在取消前先完成，服务端会保留真实结果，并对成功任务正常结算。

自己的 HTTP 客户端或网关超时，以及连接中断，都不代表服务端已确认取消。请保留原始请求体和 Idempotency-Key，用它们恢复同一次提交，或查询已知任务。立即更换请求键，可能在原任务仍运行时创建另一个任务。

遇到 503 也要查看具体错误码。SYNC_CANCEL_UNCONFIRMED 表示无法确认取消，SYNC_CLEANUP_FAILED 表示已确认取消但积分释放仍在处理中。先检查原任务与钱包状态，再决定下一步操作。

把解析状态和积分结算展示清楚

选择同步提交不会额外增加一笔解析费用，单任务或批量查询已有结果也不消费积分，但查询仍计入账户请求频率。解析成功沿用文档中的任务价格；失败、取消、到期或付费结果为空时，释放原先预留的积分。

成功响应与最终消费流水不保证在完全相同的瞬间出现。应用可以先展示已返回的结果，再通过余额和流水接口维护账户记录。不要仅因为成功后短暂保留冻结积分，就认定发生了重复扣费。

先走通一种方式，再补齐恢复流程

交互式接入可以先验证一次同步请求，分别确认可用结果和明确错误的展示。后台队列则从异步提交开始，持久保存 job_id，正确处理任务状态后，再加入批量轮询。

无论选择哪种方式，都应把 API 密钥保存在自己的服务端，保留原始来源记录，并使用受支持、自己有权处理的内容验证。完整请求字段、响应示例和错误码都在 API 文档中。给用户一个清楚的恢复动作，通常比每次超时都自动创建新任务更有用。