solvethree APIエラー：修正内容と再試行のタイミング

成功ペイロードを読み取る前に、成功以外の HTTP レスポンスを処理してください。POST /v1/tasks では、201 は新しいタスクが作成されたことを、200 は冪等な再送によって既存のタスクが返されたことを意味します。どちらのレスポンスも、解答生成の完了を意味しません。

400 — 無効なリクエスト本文

送信した本文を、そのタスクタイプについてドキュメントに記載されているフィールドと要件と照合してください。

試してみましょう： 再送信する前に入力を修正してください。無効な本文を変更せずに再試行しても解決しません。タスク作成の仕様でリクエストを確認してください。

401 — 無効な API キー

リクエストに Authorization: Bearer が含まれ、その後に有効なワークスペース API キーが続いていることを確認してください。

試してみましょう： 不足しているキーを追加するか、拒否されたキーを修正してください。ブラウザーのコードに公開せず、サーバー側で管理してください。

402 — クレジット不足

API キーに紐づくワークスペースのクレジット残高を確認してください。

試してみましょう： 再試行する前に、そのワークスペースにクレジットを追加してください。無関係な HTTP エラーやタスクの失敗を、残高の問題として扱わないでください。

403 — サイトプロファイルが無効

reCAPTCHA では、対象サイトに、ワークスペースで利用可能な有効なプロファイルがあることを確認してください。

試してみましょう： コンソールで対象サイトを設定し、プロファイルが有効であることを確認してください。タスクにホスト名とアクションを指定しても、プロファイルは作成されません。このゲートウェイレスポンスは、対象のウェブサイトがアクセスをブロックした証拠ではありません。

409 — リクエスト ID の競合

同じ requestId が、以前に異なるタスク入力で使用されていないか確認してください。

試してみましょう： 元のタスクを復旧するには、元の入力を使用してください。別のタスクを作成する意図がある場合は、新しいリクエスト ID を割り当ててください。

410 — 保存済み結果の期限切れ

保存済みの結果がすでに保持されていない完了済みタスクを取得しようとしていないか確認してください。

試してみましょう： その結果の取得を停止してください。引き続き解答が必要な場合は、新しい解答生成タスクを作成してください。このステータスは API の結果保持について示すもので、対象のトークンや Cookie の有効期間を示すものではありません。

429 — レート制限

実際の Retry-After レスポンスを確認してください。

試してみましょう： 指示された時間だけ待ってから再試行し、リクエスト頻度を下げてください。制限中に同じ頻度でポーリングや送信を続けないでください。

502 — 生成サービスが利用不可

サービスが利用できない状態と、無効な入力やクレジット不足を区別してください。

試してみましょう： 時間をおいて再試行してください。同じ作成リクエストを再試行する場合は、そのリクエスト ID と、変更していないタスク入力を再利用してください。

HTTP 503 は、生成処理のキャパシティを確保できないことを意味します。時間をおいて再試行してください。同じ作成リクエストでは、そのリクエスト ID と、変更していないタスク入力を再利用してください。

• pending または solving：既存のタスクのポーリングを続けてください。まだ準備ができていないという理由だけで、代わりのタスクを作成しないでください。
• ready：ポーリングを停止して解答を読み取ってください。
• failed：ポーリングを停止して errorCode と error を確認してください。

{
  "id": "example_login_001",
  "status": "failed",
  "errorCode": "site-unreachable",
  "error": "target page did not respond"
}

ここでの site-unreachable はタスクのエラーコードであり、HTTP ステータスではありません。別の解答生成をリクエストする前に、送信した対象 URL と、ページが応答するかどうかを確認してください。ポーリングを増やしても、この失敗したタスクは再開されません。また、元のリクエスト ID で再送しても、代わりのタスクが開始されるのではなく、既存のタスクが返されます。

接続のタイムアウトは、タスクの作成失敗を証明するものではありません。同じ論理タスクを安全に復旧できるよう、最初の作成試行前に任意の requestId を指定してください。ASCII の英字、数字、アンダースコア、ハイフンを 1–64 文字使用する必要があります。

1. 1.

   タスク ID がわかる場合は、そのタスクを取得する

   GET /v1/tasks/:id を使用し、タスクのステータスを確認する前に HTTP レスポンスを処理してください。

2. 2.

   作成レスポンスが失われた場合は、元のリクエストを再送する

   同じタスク入力を同じリクエスト ID で送信してください。冪等な再送では、タスクが作成済みであれば既存のタスクが返されます。その ID のまま入力を変更しないでください。

3. 3.

   別の解答生成を開始する意図がある場合にだけ、代わりのタスクを作成する

   新しいリクエスト ID は新しい処理を表し、以前のリクエストの復旧ではありません。たとえば、終端状態となった失敗の原因を調査し、再試行すると決めた場合など、意図を持って使用してください。

再送の処理についてはリクエスト ID による復旧を、作成には成功したもののタスクがまだ実行中の場合はポーリングとタイムアウトを参照してください。