CAPTCHA API の再試行で重複タスクを防ぐ方法

タイムアウト後は同じ Idempotency-Key と本文を再利用。競合と再送可能期間、taskId の保存を解説します。

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

1 つの論理タスクに固定キーを使う

POST 前に Idempotency-Key を保存します。長さは 8〜128 バイトで、再試行時は完全に同じ本文と組み合わせます。再試行ループ内で新しい UUID を生成しないでください。

タイムアウトでも作成済みの場合があります

サーバーが受付済みで応答だけ失われた場合、新しいキーでの再送は別の課金タスクを作る可能性があります。元のキーと本文で再送し、taskId を取得したら保存して GET に切り替えます。

business operation -> persist key + exact JSON
POST -> network outcome unknown -> retry same key + same JSON
POST -> taskId available -> persist taskId -> GET only

HTTP 409 の扱い

IDEMPOTENCY_CONFLICT は同じキーが競合するリクエストに使われたことを示します。元の種類とパラメーターを比較してください。別の論理タスクには別のキーが必要ですが、元の結果が不明なときにキーだけ変えて進めてはいけません。

再送期間より長く taskId を保存

タスクの冪等レコードの保存期間は約 25 時間です。長期間の照会と重複防止のため、業務記録に taskId を保持します。古い POST を永久に再送できるとは限りません。taskId が不明なまま期間が過ぎたら、再作成前に元の処理結果を照合します。

再試行できる障害

通信障害と再試行可能な 5xx は元のキーと本文で回数を制限して再送します。制限には Retry-After に従います。不正な項目や権限は修正が必要です。エラー処理と API リファレンスを参照してください。

Python と Node.js のサンプルは保存済みキーを環境変数から読み取り、taskId で照会を再開できます。