CAPTCHA API 呼び出しで発生する ERROR_IP_BANNED を修正する方法

要約

• CapSolver API レスポンスの ERROR_IP_BANNED は、誤ったリクエストを短時間に繰り返した結果として「API へのアクセス」が制限されたことを示すものであり、タスクで使用しているプロキシがターゲットサイトにブロックされた状況とは別物です。
• 失敗しているリクエストを一旦すべて止め、ブロックが発生する直前の最初のエラー内容を特定してから、次のリクエスト送信に進んでください。
• HTTP ステータスだけではなく、レスポンスの errorCode と errorDescription を必ず確認してください。HTTP ステータスだけでこの状態を判断してはいけません。
• 公式のエラー一覧では、このコードに関するブロック時間の記述が項目ごとに食い違っています。すべてのケースで「何分後に必ず解除される」といった固定時間は当てにしないでください。
• 問題を修正した 1 件の制御されたリクエストから再開し、レスポンスが正常であることを確認しながら、徐々に並列数やボリュームを増やしてください。

CAPTCHA API への誤ったリクエストを繰り返すと、第二の問題として「同じ失敗リクエストを送り続けた結果、API アクセス自体が一時的にブロックされる」という状況を生み出すことがあります。この段階で、CAPTCHA のサイトキーを手当たり次第に差し替えたり、ワーカー数を増やしたりすると、かえって原因が見えづらくなります。最初に行うべき有効な対応は、繰り返し失敗を出している送信元を止め、その失敗理由を説明しているレスポンスを保全することです。

本ガイドでは、CapSolver が返す ERROR_IP_BANNED に焦点を当てます。ブラウザがウェブサイトからアクセス拒否されるケースや、ターゲットサービスがプロキシを拒否するケースは扱いません。これらはワークフロー上の発生箇所が異なるため、区別することが重要です。ここでの目的は、API クライアント側を修正し、返却されたエラー内容を理解し、同じ失敗パターンを繰り返さずに正規の CAPTCHA リクエストを再開することです。

この API における ERROR_IP_BANNED の意味

ERROR_IP_BANNED は、短時間に大量のエラーを発生させたことに起因する IP ブロックとして、CapSolver 公式エラーリファレンス に記載されています。これは「API クライアントの不具合を示すシグナル」として読み取るべきものであり、「CAPTCHA 自体が解けない」ことの証拠ではありません。

レスポンスの外側の JSON には errorId、errorCode、errorDescription が含まれます。実際のレスポンスで返された値は、そのままの形で残してください。「request failed」などのメッセージだけが写っているスクリーンショットでは、入力不備・残高不足・未サポートタスク・一時的ブロックといった原因の切り分けに必要な情報が欠けています。

公開されているエラー表では、現時点でこのコードに関するブロック継続時間の記述が項目によって異なっています。そのため、本ガイドでは「何分で必ず解除される」といった時間を約束しません。実際のレスポンスに記載された内容を優先し、根本原因を修正した後も待機挙動が不明確な場合はサポートに連絡してください。

CAPTCHA チャレンジと API アクセスエラーは別のイベントです。前者はウェブサイト側の認証フローに属し、後者はあなたの統合アプリケーションからソルバーサービスへ送られたリクエストに関するものです。どの接続が失敗しているのかを特定することが、有効な修正につながる第一歩です。

関連エラーコードを区別する

関連するエラーコードは、それぞれ異なる失敗条件を表します。次にどの証拠を集めるかは、文字列の違いで判断してください。「blocked」や「banned」という文字を含むものを、すべて同じプロキシの問題として一括りにしてはいけません。

返却コード	ドキュメント上の意味	実務的に最初に確認すること
ERROR_IP_BANNED	短時間の大量エラーに伴う IP ブロック	失敗ストリームを止め、直前のエラー内容を確認
ERROR_KEY_TEMP_BLOCKED	エラーの多発に伴うキーの一時ブロック	そのキーを使うすべての呼び出し元を特定し、失敗原因を修正
ERROR_RATE_LIMIT	サービスの制限を超える頻度でリクエストしている	リクエストレートと対象サービスの制限を確認
ERROR_PROXY_BANNED	タスクで指定したプロキシがターゲットサービスにブロックされている	タスク側のプロキシ状況を別途調査

上記の意味は API エラーリファレンスに基づくものです。記載した診断アクションは、それらの意味を調査するための実務的な手順であり、「すべてのアカウントで同じ上限や解除間隔が保証されている」という意味ではありません。

一般的な HTTP 429 レスポンス は HTTP レイヤーのレート制限を示しますが、アプリケーション固有のエラーコードの代用にはなりません。可能な場合は、トランスポート層の HTTP ステータスと JSON レスポンスの両方を記録してください。これは「CapSolver がテーブル内のすべてのコードに対して必ず 429 を返す」という意味ではありません。

ステップ 1: 失敗を繰り返すすべての呼び出し元を止める

個々のタスクパラメータを変更する前に、そのエラーを出し続けているリクエストを一旦停止してください。キュー、スケジュールされたジョブ、複数のワーカーが同じ統合モジュールを共有している場合、インタラクティブなスクリプトを止めただけでは、別の場所からエラーが流れ続けることがあります。

タスク生成部、ワーカーのリトライ設定、HTTP クライアントのリトライ、さらに外側のワークフローにある「失敗ジョブの再実行」設定を確認してください。1 つの論理的な処理が、複数レイヤーで再試行されていることがあります。各レイヤーが自動再開する構成だと、実際に送出されるリクエスト数は、アプリケーション上で見えているジョブ数を大きく上回る場合があります。

診断を始めるために、システム全体を再設計する必要はありません。まずは影響を受けている処理を一時停止し、どのプロセスがリクエストを送り続けているかを特定し、エラーの一部を小さくサンプリングして保全してください。「ブロックが解除されたかどうかを確認するだけのテスト」を繰り返すのは避けましょう。

Google の SRE 本の 過負荷とリトライの扱い の章では、制御されていないリトライが障害を増幅してしまう理由が説明されています。この状況では、その一般原則を「自動再試行を再開する前に、まずリクエスト内容を正す」という単純な運用ルールとして活かします。

ステップ 2: IP ブロックの直前に発生した最初のエラーを見つける

最も有益な情報は、多くの場合、最終的なブロックレスポンスよりも「その直前に繰り返されていたエラー」です。ERROR_IP_BANNED が現れる直前のレスポンスを見直し、正確なエラーコード別にグルーピングしてください。

繰り返し発生している原因として、ERROR_INVALID_TASK_DATA、ERROR_KEY_DENIED_ACCESS、ERROR_TASK_NOT_SUPPORTED、ERROR_ZERO_BALANCE などがないかを確認します。それぞれ、必要な修正が異なります。一時的に待てばアクセスが回復することもありますが、無効なフィールド、誤った認証情報、未サポートのタスクタイプ、アカウント状態といった根本原因は、待機では解消されません。

繰り返し発生している各エラーについて、以下を残してください。

• エンドポイント
• タイムゾーン付きのタイムスタンプ
• タスクタイプ
• 機密情報を伏せたうえでのペイロード構造
• レスポンスのコードと説明文

タスク ID は、API が実際に返してきた場合にのみ記録してください。タスク作成に失敗し ID が発行されていないリクエストに対して、存在しない ID を「でっちあげる」べきではありません。

有用なインシデント記録は、次の程度の小さなもので十分です。「代表的な失敗リクエスト 1 件」「その直前のエラー」「ブロックが始まった時刻」「影響を受けた呼び出し元の集合」。アカウント認証情報、プロキシパスワード、Cookie、レスポンストークン、ページの機密データなどは、共有ログには含めないでください。

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

自動化の予算を今すぐブースト！
チャージ時にボーナスコード CAP26 を利用すると、すべてのリチャージ額に対して 5% のボーナス が無制限に付与されます。
今すぐ CapSolver ダッシュボード から引き換えましょう。

ステップ 3: 失敗しているレイヤーでリクエストを修正する

直前のレスポンスで特定した問題を、該当タスクの最新ドキュメントを参照しながら修正してください。認証情報、CAPTCHA パラメータ、ネットワーク経路、リトライ挙動などを一度にすべて変えるのは避けましょう。後のリクエストが成功しても、どの変更が効果的だったのか判断できなくなります。

キーが拒否されている場合は、稼働中プロセスが意図したアカウント資格情報を確実に受け取り、ドキュメント通りの場所に渡しているか確認してください。公式 API エラーリファレンス では、却下されたアカウントキーが別コードとして定義されています。ローカル設定ファイルに正しいキーが書かれていても、ワーカーが同じ値を読み込んでいるとは限りません。

タスクデータが無効とされている場合は、送信している JSON をタスクの最新スキーマと照合してください。必須フィールドとタスクタイプを正確に確認します。キューに溜まっているペイロードは、アプリケーションのデフォルト設定を修正した後でも古い設定を保持している可能性があります。「実際に送信されているもの」を検査してください。

タスクタイプが未サポートであれば、そのタスク生成を停止し、再試行前にサポート対象かどうかを確認してください。残高や決済に起因する問題であれば、対応するアカウントワークフローによって状態を解消します。これらは根本的な失敗の修正であり、「リトライ回数を増やす理由」にはなりません。

もし返ってきているコードが ERROR_PROXY_BANNED であれば、タスクプロキシのトラブルシューティングガイド に従ってください。タスク内で指定したプロキシは、API リクエストを送っているアプリケーションとは別の接続を表します。そのプロキシを変更しても、API コール側の ERROR_IP_BANNED が解消した証拠にはなりません。

ステップ 4: 制御された 1 件のリクエストから再開する

関連する待機時間もしくはサポートからの案内に従ってから、自動的に失敗しているストリームは停止させたまま、修正済みのリクエストを 1 件だけ送信して再開してください。目的は、同じエラー量を即座に再発させることなく、サービスが実際に返すレスポンスを観察することです。

サーバーが Retry-After ヘッダー を提供している場合は、その意味に従ってください。すべての CapSolver エラーにこのヘッダーが含まれるとは限らず、ヘッダーが無いからといって「すぐにリトライしてよい」という意味になるわけでもありません。

新しいレスポンスを以前のものと比較します。

• IP ブロックコードが残っている場合は、そこで再度停止し、その証拠一式をサポートに渡してください。
• ブロックが消え、元のタスクデータエラーが戻ってきた場合は、根本修正が不完全です。
• リクエストが受理された場合は、通常の結果フローに従い、そのステージが正常に動作しているかを確認します。

タスク作成の成功は、あくまでチェックポイントの 1 つに過ぎません。その後のソルビングエラーや、アプリケーション側でのトークン拒否などは、別途ハンドリングが必要です。元のエラーパターンが再発するかを観察できる程度のペースで徐々に負荷を戻し、ワーカー側には修正後のエラー分類を維持させることで、恒久的な入力不備が自動リトライループへと変質するのを防いでください。

サポート調査に役立つ情報

サポートへの問い合わせは、API 側の失敗内容と、すでに試した対応を明示できているほど有用です。以下の情報を、指定されているサポートチャネルから提供してください。

• 正確なエラーコードと説明文
• 発生開始時刻（タイムゾーン付き）
• 影響を受けているエンドポイント
• タスクタイプ
• 返却されたタスク ID（存在する場合）

あわせて、

• エラーを出している呼び出し元を停止済みかどうか
• ブロックの直前にどのエラーが出ていたか
• 制御された再テストの前に何を修正したか
• 同じ設定を共有している複数環境がある場合、どの環境に影響があるか

も説明してください。サービス提供側は、「IP がブロックされている」という一文から推測するよりも、影響範囲が特定されている方が、原因となったリクエスト経路を的確に調査できます。

例示には必ずマスキングを施してください。フィールド名や、再現に必要な最小限のコンテキストだけを示し、アカウントキー、プロキシ資格情報、Cookie、トークンなどの機密情報は除外します。サポート側から追加の機密情報が必要と案内された場合は、公開スクリーンショットや Issue コメントではなく、指定された安全なチャネルでのみ提供してください。

同じ失敗を繰り返さないために

再発防止の起点は、「明らかに無効なリクエスト」と「一時的な障害」を別扱いにすることです。送信前に必須フィールドを検証し、返ってきたエラーコードを保存し、設定ミスと判定できるレスポンスに対しては、同じ内容のリクエストを無制限にリトライしないようにしてください。

共有ワーカープールを利用している場合、エラーを個々のワーカーログだけでなく、キュー側からも見える形にすることが重要です。そうしないと、あるワーカーで失敗したジョブが、同じ無効な入力を抱えたまま別のワーカーにすぐピックアップされてしまいます。重要なのは「CAPTCHA への正しいリクエストを作ること」であり、「試行回数を増やすこと」ではありません。

最終的な教訓は、具体的な手順として次の 4 点に集約できます。

1. リクエストストリームを一時停止する
2. 最初に発生したエラーを特定する
3. その原因を修正する
4. 制御されたテストで再開する

このシーケンスに従うことで、各変更に対する証拠が得られ、API アクセス、CAPTCHA ソルビング、ターゲット側の検証を混同せずに扱えるようになります。

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

CapSolver は、あなたが正当に権限を持つワークフロー内の「CAPTCHA ステップ」を担当させる形で利用してください。ブラウザ、ソルバー結果、アプリケーション最終結果を別々のチェックポイントとして扱うことで、「ツール呼び出しは成功したがタスクは失敗していた」といった状態を見逃さないようにします。

FAQ

Q: ERROR_IP_BANNED は、ウェブサイトが私のプロキシを BAN したのと同じ意味ですか？

いいえ。CapSolver では、ターゲットサービスによってタスクプロキシがブロックされた場合は ERROR_PROXY_BANNED を別途定義しています。実際に返ってきたコードを使って、どの接続に問題があるのかを特定してください。

Q: どのくらい待ってから再試行すべきですか？

単一の「万能な待機時間」に頼らないでください。公開されているエラー一覧では、このコードに対するブロック時間の記述が一貫していません。失敗リクエストを止めて原因を修正したうえで、実際のレスポンスとサポートからの案内に従ってください。

Q: IP をローテーションしたり、新しいキーを作ったりしてでもリトライを続けるべきですか？

いいえ。繰り返し発生しているリクエストエラーを修正し、サービス側のアクセスガイダンスに従ってください。識別子や経路を変えることは、根本的な不具合が直った証拠にはなりません。

Q: 並列数を減らせば、無効なタスクデータは直りますか？

直りません。並列数削減はリクエスト圧を下げる効果はありますが、無効なタスクデータ自体は修正が必要です。元のエラーメッセージと、実際に送信されているペイロードを確認してください。

Q: スクリプトを止めたのに、なぜエラーが続くのですか？

別のワーカーやスケジュール、リトライレイヤーが依然としてリクエストを送り続けている可能性があります。または、一時的なブロックがまだ有効な状態かもしれません。まずはどの呼び出し元が動いているかを確認し、そのうえでレスポンスやサポートからの指示に従ってください。

Q: 再テストが成功したら、CAPTCHA ワークフロー全体が直ったと見なしてよいですか？

いいえ。そのレスポンスが示すステージだけが確認できたに過ぎません。タスク完了までの流れと、アプリケーションにおける最終的な結果は、別途検証してください。