> ## Documentation Index
> Fetch the complete documentation index at: https://docs.querying.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# エラー

> エラーエンベロープ、APIが返すすべてのコード、再試行する価値のあるケース。

失敗はひとつのエンベロープを共有します。

```json theme={null}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [{ "field": "payload.prompt", "message": "payload.prompt or payload.query is required" }],
    "timestamp": "2026-07-09T04:12:00.000Z"
  }
}
```

`code` は安定しており、分岐に使って安全です。`message` は人間向けで変わることがあります。`details` は
問題のフィールドを特定できるときに含まれます。

## コード

| コード | ステータス | 意味 | 再試行 |
| - | - | - | - |
| `MISSING_API_KEY` | 401 | Bearerトークンがない、または誤っています。 | いいえ、キーを修正 |
| `VALIDATION_ERROR` | 400 | 本文の形式不正、不明な `taskType`、または `payload.prompt` と `payload.query` の両方がない。 | いいえ、リクエストを修正 |
| `REGION_UNSUPPORTED` | 422 | このエンジンは指定された `country` を決して提供できません。 | いいえ、別のエンジンか地域を選択 |
| `REGION_UNAVAILABLE` | 422 | 現在このエンジンでは指定された `country` の容量がありません。 | 後で、容量が戻ってから |
| `RESOURCE_ALREADY_EXISTS` | 409 | 単発エンドポイントで `idempotencyKey` が重複しています。 | いいえ、タスクは既に存在 |
| `PAYLOAD_TOO_LARGE` | 413 | バッチ本文が8 MBを超えています。 | いいえ、小さく分けて送信 |
| `RESOURCE_NOT_FOUND` | 404 | 不明なタスクid、または24時間の公開ポーリング期間を過ぎています。 | いいえ |
| `ENQUEUE_ERROR` | — | バッチ内の項目ごとの失敗(例: あるレーンでの一時的なDB障害)。HTTPステータスではなく `results[].error` にのみ現れます。 | はい |

<Note>
  `400` は解析や理解ができないリクエストに使います。`422` は形式は完全に正しいものの、指定された地域では
  提供できないリクエスト専用です。ステータスより `error.code` で分岐するほうが長く安定します。
</Note>

## 地域による拒否

2つの地域コードはいずれもタスクをキューに入れる**前に**判定されます。タスクが再試行予算を使い切って
症状だけのエラーで失敗するのを待つ必要はなく、すぐに分かります。

`REGION_UNSUPPORTED` は恒久的です。そのエンジンは指定された国を提供できません。

```json theme={null}
{
  "success": false,
  "error": {
    "code": "REGION_UNSUPPORTED",
    "message": "CHATGPT cannot be served for country='CN': no proxy vendor has exit supply in CN. This is a permanent capability gap, not a transient one — retrying will not help. GOOGLE and AIMODE are unaffected by exit-IP limits and remain available for this country.",
    "details": { "taskType": "CHATGPT", "country": "CN", "cause": "no_proxy_route", "retryable": false },
    "timestamp": "2026-07-09T04:12:00.000Z"
  }
}
```

[提供できない組み合わせの表](/ja/engines/capacity)を参照してください。

`REGION_UNAVAILABLE` は一時的です。経路はありますが、今は提供できるものがありません。
[`GET /capacity`](/ja/api-reference/capacity) で各地域が現在提供できる範囲を確認してください。

## バッチの失敗は項目ごと

正しい形式のバッチは、中のタスクがすべて失敗しても常に `200` を返します。HTTPステータスは*リクエスト*を、
`results[].success` は各*タスク*を表します。

```json theme={null}
{
  "success": true,
  "summary": { "total": 3, "succeeded": 2, "failed": 1 },
  "results": [
    { "success": true,  "index": 0, "task": { "...": "..." } },
    { "success": false, "index": 1, "error": { "code": "REGION_UNAVAILABLE", "message": "..." } },
    { "success": true,  "index": 2, "task": { "...": "..." } }
  ]
}
```

リクエスト全体が不正な場合(JSONでない、配列でない、空、500件超、8 MB超、認証失敗)にのみ、バッチ自体が4xxを返します。

<Note>
  バッチ項目は `REGION_UNAVAILABLE` または `ENQUEUE_ERROR` で失敗することがありますが、どちらもこのAPIが
  実装する非同期タスク契約の項目別エラーenumにはありません。いずれも置き換えではなく追加であり、
  `VALIDATION_ERROR` と `RESOURCE_ALREADY_EXISTS` は変わりません。
</Note>

## タスクレベルの失敗

キューに入った*後に*失敗したタスクは、HTTPエラーを一切生みません。終了ステータスで分かります。

```json theme={null}
{
  "success": true,
  "task": { "id": "8f2c1e40-...", "status": "FAILED", "...": "..." },
  "credits": { "creditsToCharge": 0, "creditsCharged": 0 },
  "error": "ENGINE_TIMEOUT: The engine did not answer before the task deadline."
}
```

形の違いに注意してください。このトップレベルの `error` は、リクエストレベルのエラーが使う
`{code, message, timestamp}` オブジェクトではなく**文字列**です。コードで始まり、そのコードごとに決まった
文が続くため、コードで分岐してください。`ENGINE_TIMEOUT`、`ENGINE_NO_RESULT`、`ENGINE_FAILED` のほか、時間内に
処理枠が空かなかった場合は `NO_IP_AVAILABLE` または `NO_ACCOUNT_AVAILABLE` です(通常は後で再試行すれば成功します)。
`BAD_PAYLOAD` と `PAGE_UNAVAILABLE`(匿名では読めないNAVERのページ)は、何を変えればよいかを示すメッセージを
そのまま返します。同じタスクは `task.status === "FAILED"` のWebhookも配信します。