CAPTCHA APIリクエストで発生する ERROR_INVALID_TASK_DATA の修正方法

要約

• ERROR_INVALID_TASK_DATA は、送信したタスクデータが正しくないことを意味します。返却された errorDescription が診断の起点です。
• HTTP で実際に送信された最終的な JSON を、そのタスクタイプの最新ドキュメントと照合してください。
• 再試行の前に、フィールド名、必須値、JSON 型、ネスト構造を確認します。
• 直接 API に送るペイロードと MCP ツール引数は別の契約です。混同しないでください。
• まず特定された入力上の問題を直してください。同じリクエストを繰り返しても、パラメータ修正にはなりません。

CAPTCHA リクエストが有効な結果を返す前に失敗すると、複数の設定を一度に変えたくなります。ERROR_INVALID_TASK_DATA の場合は、まずレスポンスを保持し、API に実際に到達したリクエストを検査するほうが有効です。

CapSolver は、このエラーを「誤ったタスクデータが送信された」と定義し、ユーザーをエラー説明へ誘導しています。コードだけでは「共通の不足フィールド」は特定できません。選択したタスクタイプ、その必須入力、およびサーバーからの具体的メッセージが、調査すべき対象を決めます。

本ガイドはリクエスト診断を扱います。あらゆる不正なリクエストが必ずこのコードになることや、API が一定の順序でフィールドを検証することを主張するものではありません。

ERROR_INVALID_TASK_DATA は何を意味しますか？

処理対象のリクエストに対して、送信されたタスクデータが受け入れられないことを示します。

公式エラーリファレンス では、ERROR_INVALID_TASK_DATA は、未対応のタスクタイプ、不正な画像データ、認証エラー、解決失敗などとは別個に掲載されています。すべての失敗を「CAPTCHA 失敗」で一本化せず、errorCode と errorDescription の全文を保持してください。

直接 API では、エラーの有無を errorId で示します。レスポンスにエラーが報告されている場合、有効な taskId やソリューションが存在するかのように処理を続けてはいけません。まず診断フローへ分岐させてください。

API パラメータ には、名前、値の型、リクエスト内での位置があります。あなたのアプリケーション上では意味のある値でも、間違ったキーに入れたり、誤った JSON 型でシリアライズされていると、インターフェース上は誤りになります。

たとえば、あるツールラッパーは website_url を受け付ける一方、直接のタスクは websiteURL を使うかもしれません。どちらの表記も「常に正しい」わけではなく、それぞれが自分のインターフェースに属しています。エラー調査は、まずどのインターフェースに対してコードが呼び出しを行っているかの特定から始める必要があります。

ステップ 1: レスポンスと送信リクエストをセットで保持する

同一の失敗試行から、エラーコード、説明、タスクタイプ、およびマスク済みの最終ペイロードを取得しておきます。

アプリケーションが設定値・デフォルト・シリアライズ処理をすべて適用した「後」のオブジェクトを検査してください。スクリプトの途中で正しく見えた変数が、そのまま HTTP クライアントから送信されたことにはなりません。

日常的なログでは、アカウントキー、完全なソリューション値、Cookie、機密ページデータを除去します。一方で、パラメータ名と安全な型情報は保持してください。サポートにタスク参照が必要な場合は、複数の再試行から情報を寄せ集めるのではなく、対応する試行とセットで保存します。

有用なトラブルシューティングメモには、エンドポイント、タスクタイプ、存在するフィールド名、JSON 型、正確なエラーテキストが含まれます。また、そのリクエストが直接送信されたものか、SDK で生成されたものか、MCP ツール呼び出しを変換したものかも記載してください。このインターフェース種別が、いかにも正しく見えるフィールドがなぜ拒否されているのかを説明してくれる場合がよくあります。

デバッグを容易にするためだけに、マスクしていないリクエストを公開 Issue やモデルへのプロンプトに貼り付けないでください。診断記録は、適切な社内チャンネルに保管してください。

ステップ 2: 個々のフィールドの前に「包み」を確認する

直接の createTask リクエストでは、外側のオブジェクトを createTask ドキュメント と比較してください。

以下の JSON は、ドキュメントの reCAPTCHA v2 プロキシレス タスクに基づいた例示的なリクエスト形状です。資格情報やページ値はプレースホルダであり、送信されたリクエストでも利用可能なチャレンジ例でもありません。

{
  "clientKey": "YOUR_API_KEY",
  "task": {
    "type": "ReCaptchaV2TaskProxyLess",
    "websiteURL": "https://example.com/authorized-form",
    "websiteKey": "PUBLIC_SITE_KEY_FROM_THAT_PAGE"
  }
}

ここでは、clientKey は task の外側にあり、タスク固有の入力は内側にあります。task の値は JSON オブジェクトであり、エスケープされた JSON 文字列ではありません。

この形はパースされ、現在の reCAPTCHA v2 パラメータ表 と照合されています。これらのプレースホルダで解決リクエストは実行されていません。実際のリクエストには、あなた自身の認証情報、許可されたページ、およびその実際のチャレンジパラメータが必要です。

まず構造を比較してください。もしリクエストビルダーが誤ってタスクを引用符付き文字列に変換してしまっている場合、サイトキーを変更しても包みは修復されません。ボディがフォームエンコードで送信されているのに、クライアントコード側では JSON だと想定している場合は、チャレンジ固有の値を編集する前にシリアライズ経路を確認してください。

ステップ 3: 各フィールドをタスクの正確なドキュメントと比較する

複数のサンプルからフィールドを寄せ集めるのではなく、実際のタスクバリアントに対応するパラメータ表を使用してください。

これはレビュー順序であり、サーバーの検証順を主張するものではありません。エラー説明がより具体的な問題を直接示すこともあります。その場合はまずその手がかりに従ってください。

「念のため」にあらゆるオプションパラメータを追加するのは避けてください。余計な当てずっぽうは、かえってリクエストを理解しにくくします。まずドキュメント上の必須フィールドから構成し、次に実際のバリアントで必要な値だけを加えます。ある CAPTCHA 系列で必要なフィールドが、別の系列ではまったく意味を持たない場合もあります。

条件付きフィールドであれば、その条件を必ず読みましょう。オブジェクトを「完全に見せる」目的だけで、空のプレースホルダをでっち上げないでください。例えば、別の reCAPTCHA v2 ドキュメント がバリアント固有のマッピングを説明していても、それを理由にすべてのリクエストへ任意の s 値を追加してよいわけではありません。

CapSolver ボーナスコードを利用する

自動化予算をその場で増強しましょう！
CapSolver アカウントにチャージする際、ボーナスコード CAP26 を使うと、すべてのリチャージに対して 5% のボーナス が無制限に付与されます。
今すぐ CapSolver ダッシュボード で引き換えましょう。

ステップ 4: REST・SDK・MCP の命名を分離する

アプリケーションが実際に利用している境界の契約を確認してください。

MCP サービスドキュメント はツール呼び出しを説明し、直接 API リファレンスは HTTP タスクオブジェクトを説明しています。SDK やツールスキーマの関数パラメータが、そのまま同名のキーとして REST ペイロードに登場するとは限りません。

仮にアプリケーションがエージェントから website_url を受け取るとします。その引数を公開している MCP ツールを呼び出すのであれば、そのスペルは適切かもしれません。しかし直接の reCAPTCHA タスクを組み立てるなら、リクエストビルダーはドキュメントどおりの websiteURL フィールドを生成しなければなりません。ツール引数をそのまま task にコピーすると、本来必要なマッピング処理が抜け落ちます。

同様に、エージェントアダプターが公開するタイプ名が、そのまま REST タスククラス名になるとは限りません。無関係なサンプルからクラス名を拝借するのではなく、アダプターの最新スキーマと実装経路を確認してください。

統合コード内に小さなマッピングを保持し、ローカルでテストしてください。シリアライズテストは、プログラムが期待どおりの JSON 形状を生成しているかを確認できますが、公開サイトキーが正しいこと、アカウントが認可されていること、実際の解決が成功することまでは保証できません。

Python ユーザー向けには、標準 JSON ドキュメント に、辞書・文字列・boolean・null がどのようにシリアライズされるかが説明されています。JavaScript ユーザーには、JSON.stringify のドキュメント が、どこでオブジェクトが JSON 文字列になってしまうかを特定する助けになります。HTTP クライアントの「JSON ボディ API」に従い、同じオブジェクトを二重にシリアライズしないでください。

ステップ 5: 具体的な修正後にだけ再試行する

証拠に基づいた修正を 1 つ行い、その修正を加えたリクエストを送信し、次の変更を加える前に新しいレスポンスを確認してください。

タスクが受理され、非同期タスク識別子が返された場合は、ドキュメントどおりの getTaskResult フロー を使用します。最初に受理されたリクエストの完了待ちの間に、タスクを作成し続けてはいけません。

新しいエラーコードは新しい証拠です。たとえば、未対応タスクエラーが出た場合は、調査対象をサポートされているタスクタイプに移すべきですし、画像解析エラーが出た場合は提出した画像へと移すべきです。すべてのレスポンスを元のデータエラーとみなしたままにしないでください。

説明文がサービス制限や未サポート用途を示している場合、無関係なパラメータを変更しても解決策にはなりません。その試行は中止し、ドキュメントに記載された制限を正規の窓口を通じて解決してください。

サービスがソリューションを返した後も、ブラウザやアプリケーションは、そのソリューションを目的の操作のために取り込み、検証する必要があります。修正済みリクエストは入力上の問題が解決されたことを示しますが、別のフォーム項目やビジネスルールまで通過することを保証するものではありません。

エラーが解消しない場合、サポートに何を送るべきですか？

失敗した形状と正確なエラーテキストを保持した、最小限かつマスク済みの再現例を送ってください。

タスクタイプ、使用したインターフェース、該当すれば SDK やパッケージのバージョン、安全に開示できるフィールド名と型、エラーコードと説明、試行時刻を含めます。タスク参照が返されていれば、それも含めてください。既に試した修正と、その結果のレスポンスも記載します。

無関係なアプリケーションロジックや秘匿すべき値は除外してください。フィールドを削除した結果、挙動が変わるのであれば、その観察結果を記録しますが、それがより広い原因を証明していると決めつけてはいけません。目的は、この特定の失敗を説明できる「最小のリクエスト差分」を特定することです。

ローカルの JSON パース成功だけをもって「成功」としないでください。パースは構文を確認しているだけであり、サービス側では依然としてタスク契約とコンテキストを評価しています。これらを分けて考えることで、サポートレポートははるかに対応しやすくなります。

CapSolver で信頼性ある自動化ワークフローを構築する

信頼性の高い CAPTCHA リクエストは、正しい契約と観測可能な入力データから始まります。CapSolver は、そのステップのための文書化されたソルバーインターフェースを提供します。CapSolver を試して、許可されたテストワークフローで利用し、最終的なアプリケーション側のチェックは切り離しておいてください。

FAQ

Q: ERROR_INVALID_TASK_DATA は常に websiteKey が間違っているという意味ですか？

いいえ。このコードは、広い意味で「不正なタスクデータ」を表します。特定のフィールドを名指しする前に、errorDescription を読み、送信ペイロードを選択したタスクのドキュメントと比較してください。

Q: 同じリクエストを何度も再試行すべきですか？

内容を変えない再試行では、既知の入力不一致は修正されません。まず関連するデータを特定して修正し、そのうえで次のレスポンスを確認してください。

Q: JSON としては正しいリクエストでも、タスクデータが不正になることはありますか？

はい。JSON が正しいことは構文レベルの確認に過ぎません。必須フィールド、値の型、ネスト構造、タスクの選択、チャレンジの文脈といった検査は別に行われます。

Q: website_url と websiteURL は互換ですか？

いいえ。使用しているインターフェースが要求する表記を使ってください。MCP ツール引数と直接の REST タスクフィールドでは、名前が異なる場合があります。

Q: API が修正済みリクエストを受け入れたのに、ページ側で結果が拒否される場合は？

それは後段の問題として扱ってください。ソルバー結果のステータスを保持し、ページ側の現在の拒否要因を別途調査します。元の入力エラーが残っていると決めつけないでください。