非同期 CAPTCHA API を安全にポーリングする方法

期限付きのループで待機中と uncertain を扱い、クライアントの期限後も同じタスクを照会する方法。

許可された QA 自動化とブラウザー連携向けです。テスト権限のあるサイトと業務フローでのみ使用してください。

HTTP の成功とタスクの完了は別です

作成リクエストは受付時に HTTP 202 を返します。待機中のタスクを GET しても HTTP 200 が返ります。solution を読む前に status を確認します。

状態	クライアントの動作
queued / dispatching / processing	2〜3 秒待ち、同じタスクを照会。
completed	許可されたアプリで結果を使用。
failed / cancelled	停止し、エラーと課金結果を確認。
uncertain	taskId を保存し確認継続またはサポートに連絡。安易に再作成しない。

期限付きのループ

リクエストごとのタイムアウトと全体の期限を設定します。Python と Node.js のサンプルは 1 リクエスト最大 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 を保存して停止します。認証・権限エラーは修正が必要で、連続照会では解決しません。

照会の重複を防ぐ

通常は 1 タスクにつき 1 つのポーラーで十分です。業務記録に taskId を保存してワーカー間を調整し、終了時にタイマーを停止します。Webhook も利用でき、設定と配信動作は API リファレンスにあります。

uncertain が続く理由

処理結果の照合が継続中の場合、資金も予約されたままです。同じタスクを照会し、サポートには taskId とリクエスト ID を伝えます。API Key は送信しないでください。料金と予約額も参照してください。