验证码 API 如何安全轮询异步任务

通过有截止时间的循环处理排队与 uncertain 状态；客户端超时后继续查询原任务，避免重复建单。

适用于授权自动化测试、风控 QA 与浏览器集成。请仅在有权测试的站点和业务流程中使用。

HTTP 成功不等于任务完成

创建请求在任务被接受时返回 HTTP 202。任务仍排队时，成功的 GET 同样返回 HTTP 200。读取 solution 前必须检查 status。

状态	客户端动作
queued / dispatching / processing	等待 2–3 秒后查询同一个任务。
completed	在授权应用中使用结果。
failed / cancelled	停止轮询，检查任务错误与计费结果。
uncertain	保存 taskId，继续核对或联系支持，不盲目重建。

有截止时间的轮询

同时设置单次请求超时和客户端总截止时间。可下载的 Python 与 Node.js 示例每次请求最多 20 秒，总预算 240 秒，轮询间隔 3 秒。这些是客户端示例预算，不是服务时效保证。

save taskId
until client deadline:
    GET the same taskId
    completed -> return solution
    failed or cancelled -> stop
    queued, dispatching, processing or uncertain -> wait
on deadline -> persist taskId and stop local polling

稍后可用保存的 ID 恢复查询。客户端截止不会取消任务，也不能证明任务失败。GET 超时后不要 POST 新任务。

轮询请求失败时

区分 GET 请求故障与任务状态。429 和可重试 5xx 要遵守 Retry-After，并设置重试上限。如果等待时间超过预算，停止本地查询并保存 ID。认证或权限错误需要修正，不能通过密集轮询解决。

避免重叠轮询

通常每个任务只需一个轮询器。在业务记录中保存 taskId，协调工作进程，在流程结束时清理定时器。Webhook 可减少轮询；配置与投递行为见 API 参考。

为什么任务仍是 uncertain？

处理结果可能仍待核对，资金也可能仍预占。查询原任务，向支持提供 taskId 和请求编号，不要发送 API Key。参见计费与预占。