# エラーコード

> YesCaptcha API の全エラーコードの意味と対処方法を、リクエスト形式、アカウントと残高、同時実行と一時停止、タスク結果、サイトパラメータ、画像、プロキシ、サーバー側に分けて説明します。エラーを返したリクエストは課金されません。

Source: https://docs.yescaptcha.com/ja/api/errors/ · Last verified: 2026-10-15

> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/api/errors/

API がエラーを返すときは `errorId: 1` となり、`errorCode` にエラーコード、`errorDescription` に説明文が入ります。エラーを返したリクエストは課金されません。タスク作成時のエラーは課金されず、作成後に認識が失敗した場合やタイムアウトした場合は自動的に返金されます。

> **ヒント:** プログラムでは `errorCode` で判定してください。`errorDescription` の文言は変更されることがあるため、判定に使わないでください。

```json
{
  "errorId": 1,
  "errorCode": "ERROR_ZERO_BALANCE",
  "errorDescription": "帐户余额不足"
}
```

## 対処方針

1.  **パラメータ系のエラー**（リクエスト形式、clientKey、タスクタイプ、サイトパラメータ、画像）は、そのまま再送しても結果は変わりません。先にリクエストを修正してください。
2.  **認識の失敗とタイムアウト**（`ERROR_CAPTCHA_UNSOLVABLE`、`ERROR_TASK_TIMEOUT`）は、新しいタスクを作成して再試行できます。
3.  エラーが出たら、その `taskId` の**ポーリングを停止**してください。同じリクエストをそのまま高頻度で再送しないでください。
4.  「自動一時停止にカウント」と表示されているエラーは、同じ `clientKey` で 1 分間に 100 回発生すると、タスクの作成が 5 分間一時停止されます。「キャッシュ」と表示されているエラーはカウントされませんが、キャッシュ期間中は同じリクエストに対して元のエラーがそのまま返されます。詳しくは [同時実行数の上限と自動一時停止](https://docs.yescaptcha.com/ja/api/rate-limits.md) を参照してください。

## エラーコード一覧

### リクエスト形式

| エラーコード | 意味 | 対処方法 |
| --- | --- | --- |
| `ERROR_REQUIRED_FIELDS` | 必須フィールドが不足しています(`clientKey` や、タスクタイプで必要な `websiteURL` / `websiteKey` など)。またはリクエストボディが JSON ではありません | タスクタイプのページに記載されている不足フィールドを追加し、`POST` と `Content-Type: application/json` で JSON を送信してください |
| `ERROR_REQUEST_FORMATS` (自動一時停止の対象) | リクエストボディが有効な JSON ではありません | 文字列を連結せず、JSON ライブラリでボディを生成してください。JSON に `//` コメントを含めることはできません |
| `ERROR_TASK_ABSENT` (自動一時停止の対象) | `createTask` の呼び出しに `task` フィールドがありません | タスクのパラメーターを `task` オブジェクトに入れてください。Python requests では `data=data` ではなく `json=data` を使用してください |
| `ERROR_TASK_NOT_SUPPORTED` (自動一時停止の対象) | `task.type` のスペルが間違っているか、そのタイプがすでに廃止されています | 「タスクタイプと料金」からタイプ名をコピーしてください。大文字と小文字は区別されます |
| `ERROR_PAGE_NOT_FOUND` | リクエストされたパスが存在しません | エンドポイントの URL(例: `https://api.yescaptcha.com/createTask`)を確認してください。メソッド名は大文字と小文字が区別されます |
| `ERROR_BAD_REQUEST` | リクエストを処理できません。多くの場合、HTTP メソッドの誤り(POST ではなく GET を使用)またはパラメーター値が無効であることが原因です | `POST` で JSON を送信し、パラメーターの型と値を確認してください |
| `ERROR_ILLEGAL_PARAMETERS` | パラメータの値が無効です。Cloudflare チャレンジページでよく発生します：`websiteURL` が公開された `http://` / `https://` の URL ではない、`postData` がオブジェクトではない、または `requiredCookies` が文字列の配列ではない場合（createTask が返し、課金されません）。あるいは、プロキシ経由で対象ドメインを名前解決できなかった場合（getTaskResult が返し、自動的に返金されます） | タスクタイプのページにあるパラメータ表に従って値を修正してください。ドメインを名前解決できなかった場合は、URL のスペルと、プロキシがそのサイトにアクセスできるかを確認してください |

### アカウントと残高

| エラーコード | 意味 | 対処方法 |
| --- | --- | --- |
| `ERROR_KEY_DOES_NOT_EXIST` (自動一時停止の対象) | `clientKey` が存在しません。コピー時に文字が増減した、またはダッシュボードでキーがリセットされた可能性があります | yescaptcha.com のダッシュボードからキーをもう一度コピーしてください。スペースや改行を含めないでください |
| `ERROR_KEY_EXPIRED` (自動一時停止の対象) | `clientKey` の有効期限が切れています（createTask と getBalance で返され、課金されません）。次のいずれかです。長期間使用されなかったため、アカウント保護のためにシステムが有効期限を設定した場合（期限前にメールで通知されます）、またはこの `clientKey` に設定した有効期限が過ぎた場合 | yescaptcha.com のダッシュボードにサインインします。長期間未使用で期限切れになった場合は、新しい `clientKey` を生成してください。残高は新しい `clientKey` に自動的に移行されます。有効期限を設定していた場合は、期限を変更するか、別の `clientKey` を使用してください。その後、プログラム内の `clientKey` を新しいものに更新してください |
| `ERROR_KEY_IP_NOT_ALLOWED` | この `clientKey` には IP 許可リストが設定されており、リクエスト元の IP がリストに含まれていません（createTask と getBalance で返されます。課金されず、自動一時停止の回数にも含まれません） | yescaptcha.com のダッシュボードにサインインし、リクエストを送信しているマシンのパブリック IP をこの `clientKey` の許可リストに追加するか、別の `clientKey` を使用してください。複数のマシンから API を呼び出す場合は、すべてのマシンのパブリック IP を追加してください（ここでの IP は YesCaptcha API を呼び出す側の IP であり、タスクパラメータ内のプロキシではありません） |
| `ERROR_KEY_QUOTA_EXCEEDED` | この `clientKey` には利用上限が設定されており、現在の期間の残り上限がこのタスクの課金額に足りません（createTask で返されます。課金されず、自動一時停止の回数にも含まれません）。上限は実際に課金されたポイントで計算され、失敗またはタイムアウトしたタスクで返金されたポイントは上限に戻ります | yescaptcha.com のダッシュボードにサインインしてこの `clientKey` の上限を引き上げるか、次の期間まで待つか（北京時間で毎日、毎週月曜日、または毎月 1 日にリセットされます。一回限りの上限はリセットされません）、別の `clientKey` を使用してください。この `clientKey` の残り上限は `getBalance` で取得できます（`keyQuotaRemaining`） |
| `ERROR_ZERO_BALANCE` | 残高が不足しています。タスクを作成するには、残高が 10 ポイントを超えている必要があります | チャージしてから再試行してください。`getBalance` で残高を確認できます |

### 同時実行数と一時停止

| エラーコード | 意味 | 対処方法 |
| --- | --- | --- |
| `ERROR_THREADS_MAXIMUM` (場合により自動一時停止の対象) | このアカウントで、このタイプのタスクが処理中の数が多すぎます。レスポンスの `limit` は現在の上限です。このリクエストは処理されず、課金もされません | 送信済みのリクエストが返るのを待つか、1〜2 秒待ってから再試行してください。同時に結果を待つリクエストの数を制限してください |
| `ERROR_IP_BLOCKED_5MIN` | この `clientKey` は短時間にエラーが多発したため、自動一時停止されました。`retryAfter` は残り秒数、`blockReason` は一時停止の原因となったエラーです | `blockReason` に従ってリクエストを修正し、`retryAfter` 秒待ってください。一時停止中にリクエストを送信しても、停止時間は延長されません |
| `ERROR_NO_SLOT_AVAILABLE` | 認識サービスが一時的に混雑しています。createTask が返した場合は課金されません。キューで長く待機したタスクも getTaskResult からこのエラーが返され、自動的に返金されます | 数秒待ってから、もう一度タスクを作成してください |

### タスクと結果

| エラーコード | 意味 | 対処方法 |
| --- | --- | --- |
| `ERROR_TASKID_INVALID` (自動一時停止の対象) | `taskId` が存在しない、有効期限が切れている(結果は約 10 分間保持されます)、別の `clientKey` のものである、または別のエンドポイントで作成されたものです | このタスクのポーリングを停止してください。作成時と同じエンドポイントと `clientKey` で照会してください |
| `ERROR_TASK_TIMEOUT` | タスクが制限時間内(通常は 110 秒)に完了しませんでした。ポイントは自動的に返金されました | 新しいタスクを作成してください。タイムアウトが続く場合は、同じキャプチャ向けの別のタスクタイプを試してください |
| `ERROR_CAPTCHA_UNSOLVABLE` | 今回はキャプチャを認識できなかったため、ポイントを返金しました。自動一時停止の対象にはなりません | タスクを作り直してください。失敗が続く場合は `websiteURL`、`websiteKey` などのパラメータを確認するか、同じ種類のキャプチャ向けの別のタスクタイプを試してください |
| `ERROR_SETTLEMENT_FAILED` (自動一時停止の対象) | 精算時に残高が不足していたため、結果は返されませんでした | チャージしてからタスクを作り直してください |
| `ERROR_NO_SUCH_CAPCHA_ID` | タスクはすでに無効です | このタスクのポーリングを止めて、新しく作り直してください |
| `ERROR_RECAPTCHA_TIMEOUT` | キャプチャの認識がタイムアウトしたため、ポイントを返金しました | タスクを作り直してください |

### 対象サイトのパラメーター

| エラーコード | 意味 | 対処方法 |
| --- | --- | --- |
| `ERROR_RECAPTCHA_INVALID_SITEKEY` (キャッシュ済み、一時停止の対象外) | `websiteKey` が無効です | ページから sitekey をもう一度探してください（パラメータの調べ方のガイドを参照）。同一のリクエストはキャッシュ期間中、このエラーがそのまま返され、レスポンスに `cached: true` が付きます |
| `ERROR_RECAPTCHA_INVALID_DOMAIN` (キャッシュ済み、一時停止の対象外) | `websiteURL` のドメインが `websiteKey` と一致しません | `websiteURL` にはキャプチャが表示されるページのアドレスを指定してください |
| `ERROR_INVALID_KEY_TYPE` (キャッシュ済み、一時停止の対象外) | sitekey が別の種類のキャプチャのものです。たとえば v3 のキーを v2 のタスクタイプで使っています | まずキャプチャの種類を判別し（「キャプチャの種類を判別する」を参照）、対応するタスクタイプを選んでください。v2 のインビジブル版では `isInvisible` を指定します |
| `ERROR_DOMAIN_NOT_ALLOWED` (キャッシュ済み、一時停止の対象外) | このサイトは現在サポートされていません | 同じ種類のキャプチャ向けの別のタスクタイプを試すか、サポートにお問い合わせください |
| `ERROR_HIGH_DEMAND_DOMAIN` (自動一時停止の対象) | このサイトは現在サポートされていません | このサイトのタスク送信を止めて、サポートにお問い合わせください |
| `ERROR_FAILED_LOADING_WIDGET` | 指定されたパラメータではキャプチャを読み込めませんでした | `websiteURL` と `websiteKey` を確認してください。独自のプロキシを使うタスクタイプでは、プロキシから対象サイトにアクセスできるかも確認してください |

### 画像

| エラーコード | 意味 | 対処方法 |
| --- | --- | --- |
| `ERROR_ZERO_CAPTCHA_FILESIZE` (自動一時停止の対象) | 画像が空、または小さすぎます | Base64 データが欠けていないか、`data:image/...;base64,` プレフィックスが付いていないか確認してください |
| `ERROR_TOO_BIG_CAPTCHA_FILESIZE` (自動一時停止の対象) | 画像が大きすぎます | 画像を圧縮または縮小してから送信してください。リクエストボディ全体を 6 MB 未満に収める必要があります |
| `ERROR_IMAGE_TYPE_NOT_SUPPORTED` (自動一時停止の対象) | 画像形式がサポートされていないか、このタスクタイプで処理できない画像です。1 回発生すると 30 分間、クライアントキーが一時停止されます | JPG または PNG を使い、画像がタスクタイプに合っているか確認してください。たとえば reCAPTCHA の画像認識では 100x100、300x300、450x450 のいずれかが必要です |
| `ERROR_ILLEGAL_IMAGE` (自動一時停止の対象) | 画像サイズがこのタスクタイプの要件を満たしていません | タスクタイプのページの説明に従って画像サイズを調整してください |
| `ERROR_PARSE_IMAGE_FAIL` | 画像をデコードできませんでした。Base64 が途中で切れている、またはプレフィックスが付いている場合によく起こります | Base64 エンコードを確認し、`data:` プレフィックスと改行を取り除いてください |
| `ERROR_UNKNOWN_QUESTION` | `question` が間違っているか、この問題文にはまだ対応していません | タスクタイプのページにある問題文の一覧と照らして確認してください。未対応の問題文はサポートにお問い合わせください。新しい問題文は通常 3 営業日以内に対応します |
| `ERROR_UNKNOW_450x450_QUESTION` | この問題文は 4×4（450x450）の画像にはまだ対応していません | ページ上でチャレンジを再読み込みして、別の問題に切り替えてください |

### プロキシ

| エラーコード | 意味 | 対処方法 |
| --- | --- | --- |
| `ERROR_PROXY_CONNECT_REFUSED` | プロキシが接続を拒否しました | プロキシのアドレス、ポート、プロトコルを確認し、外部からの接続を許可していることを確かめてください（127.0.0.1 などのローカルアドレスは不可） |
| `ERROR_PROXY_CONNECT_TIMEOUT` | プロキシへの接続がタイムアウトしました | より安定したプロキシに変更してください |
| `ERROR_PROXY_READ_TIMEOUT` | プロキシ経由のデータ読み取りがタイムアウトしました | より高速なプロキシに変更してください |
| `ERROR_PROXY_BANNED` | プロキシが利用できないか、その IP が対象サイトにブロックされています | 別のプロキシに変更してください |
| `ERROR_PROXY_INCORRECT` | プロキシのパラメータの形式が正しくありません | `proxyType`、`proxyAddress`、`proxyPort`（または `proxy` 文字列）の形式を確認してください |
| `ERROR_PROXY_TRANSPARENT` | プロキシが透過プロキシで、実際の IP が露出します | 匿名（高匿名）プロキシに変更してください |
| `ERROR_PROXY_NOT_AUTHORISED` | プロキシのユーザー名またはパスワードが間違っています | `proxyLogin` と `proxyPassword`（または `proxy` 文字列内の認証情報）を確認してください |
| `ERROR_PROXY_TLS_ERROR` | プロキシとの TLS ハンドシェイクに失敗しました。`proxyType` の指定誤り（たとえば http プロキシに https を指定）でよく起こります | プロキシのプロトコルを確認してください |
| `ERROR_PROXY_CONNECTION_FAILED` | プロキシサーバーに接続できませんでした | プロキシのアドレスとポートを確認し、プロキシが正常に動作していることを確かめてください |

### サーバー

| エラーコード | 意味 | 対処方法 |
| --- | --- | --- |
| `ERROR_SERVICE_UNAVALIABLE` | サービスが一時的に利用できません（エラーコードのつづりは `UNAVALIABLE` です） | しばらくしてから再試行してください。続く場合はサポートにお問い合わせください |
| `ERROR_INTERNAL_SERVER_ERROR` | サーバー内部でエラーが発生しました | しばらくしてから再試行してください。続く場合は `taskId` を添えてサポートにお問い合わせください |
| `ERROR_UNKNOWN` | 分類されていないエラーです | しばらくしてから再試行してください。続く場合は `taskId` を添えてサポートにお問い合わせください |

## 追加フィールド

一部のエラーのレスポンスには、追加のフィールドが含まれます。

| フィールド | 返される場所 | 説明 |
| --- | --- | --- |
| `retryAfter` | `ERROR_IP_BLOCKED_5MIN`、キャッシュされたエラー | あと何秒待つ必要があるか |
| `blockReason` | `ERROR_IP_BLOCKED_5MIN` | 一時停止の原因となったエラーコード |
| `blockDetail` | `ERROR_IP_BLOCKED_5MIN` | 一時停止の原因となったリクエストのタイプ、URL、sitekey。原因の特定に使えます |
| `cached` | キャッシュされたエラー | `true` の場合、キャッシュされた結果であり、実際には認識していません |
| `badRequest` | キャッシュされたエラー | キャッシュに該当したパラメータ |
| `limit` | `ERROR_THREADS_MAXIMUM` | 現在の同時実行数の上限 |

`errorDescription` の言語に関するルールは [リクエストとレスポンス](https://docs.yescaptcha.com/ja/api/overview.md) を参照してください。