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

# エラーと上限

> コンテキストターゲティングAPIがエラーを返す仕組み、リクエストを安全に再試行する方法、適用される上限をご案内します。

このページでは、[コンテキストターゲティングAPI](/ja/integrations/context-targeting/overview)のエラーレスポンス、一括リクエストの結果の返し方、安全な再試行の方法、リクエストに適用される上限について説明します。

***

## エラーレスポンス

失敗したリクエストには、HTTPのエラーステータスと、次のいずれかの形式のJSONボディが返されます。エラーは`message`の文言ではなく、HTTPステータスと`errorCode`で判別してください。

| ステータス | 形式 | `errorCode` |
| - | - | :-: |
| `400` | [検証エラー](#検証エラー) | なし |
| `400`、`404`、`409` | [ビジネスエラー](#ビジネスエラー) | あり |
| `401`、`403` | [認証エラーと権限エラー](#認証エラーと権限エラー) | なし |
| `413` | [リクエストボディのサイズ超過](#リクエストボディのサイズ超過) | なし |
| `500`、`502` | [サーバーエラー](#サーバーエラー) | なし |

### 検証エラー

リクエストが処理の前に拒否された場合のエラーです。フィールドの不足や無効な値、ルールに反する名前やコンテキストID、定義されていないフィールド（作成リクエストの`_id`など）、リクエストあたりの上限の超過が原因です。一括リクエストも含め、リクエストの内容は何も反映されません。

`message`は、見つかったすべての問題を並べた配列です。

```json theme={null}
{
  "message": [
    "property _id should not exist",
    "name must be 2-36 characters of Korean, English letters, digits, spaces or ~%&+- (no leading or trailing spaces)"
  ],
  "error": "Bad Request",
  "statusCode": 400
}
```

パスのIDが有効なULIDでない場合や、ボディが有効なJSONでない場合は、`message`が1つの文字列になります。

```json theme={null}
{
  "message": "Invalid ULID",
  "error": "Bad Request",
  "statusCode": 400
}
```

### ビジネスエラー

リクエストの形式は正しいものの、サーバーが処理できない場合のエラーです。たとえば、名前がすでに使われている場合や、ターゲティングが存在しない場合です。

| フィールド | タイプ | 説明 |
| - | - | - |
| `statusCode` | number | HTTPステータスコード |
| `errorCode` | string | エラーコード。[エラーコード別のエラー](#エラーコード別のエラー)を参照してください。 |
| `detail` | object | 一部のエラーコードで返される追加情報。[detailフィールド](#detailフィールド)を参照してください。 |
| `timestamp` | string | エラーが発生した時刻。一部のレスポンスにのみ含まれます。 |

別のコンテキストターゲティングがすでに使っている名前でターゲティングを作成した場合のレスポンスは、次のとおりです。

```json theme={null}
{
  "statusCode": 409,
  "errorCode": "TARGETING_NAME_DUPLICATE",
  "detail": {
    "existingId": "01JAB3XK5Q8V7M2N4P6R9T0W1Y"
  }
}
```

単一項目のエンドポイントは、その項目のエラーをそのままレスポンスとして返します。予期しないエラーで項目が失敗した場合は、代わりに`502`を返します。一括操作のエンドポイントは、項目ごとのエラーを`results`で返します。[一括操作のレスポンス](#一括操作のレスポンス)を参照してください。

### 認証エラーと権限エラー

`401`は、`x-api-key`ヘッダーがないか、キーが無効または廃棄済みであることを示します。`403`は、エンドポイントに必要なスコープをキーが持っていないことを示します。

```json theme={null}
{
  "message": "Unauthorized",
  "statusCode": 401
}
```

```json theme={null}
{
  "message": "Forbidden",
  "statusCode": 403
}
```

### リクエストボディのサイズ超過

`413`は、リクエストボディが8 MBを超えていることを示します。何も反映されません。

```json theme={null}
{
  "statusCode": 413,
  "message": "request entity too large"
}
```

### サーバーエラー

`502`は一時的なサーバーの問題でリクエストを完了できなかったことを、`500`は予期しないサーバーエラーを示します。どちらの場合も、リクエストが反映されている場合と、反映されていない場合があります。`message`の文言は変わることがあります。[再試行と重複リクエスト](#再試行と重複リクエスト)を参照してください。

```json theme={null}
{
  "message": "Upstream service error",
  "error": "Bad Gateway",
  "statusCode": 502
}
```

***

## エラーコード

### ステータス別のエラー

次のエラーには`errorCode`がありません。

| ステータス | 発生条件 | 対処方法 |
| - | - | - |
| `400` | リクエストが検証に失敗しました。何も反映されません。 | `message`をもとにリクエストを修正してください。[上限](#上限)と[名前のルール](#名前のルール)を参照してください。 |
| `401` | `x-api-key`ヘッダーがないか、キーが無効または廃棄済みです。 | APIキーを確認してください。 |
| `403` | キーに必要なスコープがありません。`GET`リクエストには`context-targeting:read`、`POST`、`PATCH`、`DELETE`リクエストには`context-targeting:write`が必要です。 | そのスコープを持つキーを使ってください。既存のキーにはスコープを追加できないため、コンソールの **\[設定]** > **\[連携]** で新しいキーを作成してください。[連携 & APIキー](/ja/integrations/overview)を参照してください。 |
| `413` | リクエストボディが8 MBを超えています。 | リクエストを分割してください。韓国語などの非ASCII文字は、`\uXXXX`形式のエスケープではなく、UTF-8のまま送信してください（例：Pythonの`json.dumps`では`ensure_ascii=False`、PHPの`json_encode`では`JSON_UNESCAPED_UNICODE`を指定）。 |
| `500`、`502` | サーバーの問題です。リクエストが反映されている場合と、反映されていない場合があります。 | 少し待ってから、同じリクエストを再送してください。[再試行と重複リクエスト](#再試行と重複リクエスト)を参照してください。 |

### エラーコード別のエラー

| ステータス | `errorCode` | 発生条件 | 対処方法 |
| - | - | - | - |
| `400` | `AD_PRODUCT_TARGETING_POLICY_LIMIT_EXCEEDED` | 変更によって、すべてのターゲティングを合わせて **必須含む** または **必須除外** に設定されたオプションが500個を超える広告商品が生じます。新しい最上位オプションが広告商品の必須設定を引き継ぐ場合や、オプショングループの削除または下位オプションの切り離しによって、下位オプションがオプショングループの設定を引き継ぐ場合に起こります。オプションの一括追加では、そのターゲティングの新しい最上位オプションがすべて失敗します。 | コンソールで`detail.products`の広告商品の必須オプションを減らしてから、リクエストを再送してください。 |
| `400` | `TARGETING_CATEGORY_LIMIT_EXCEEDED` | 下位オプションを含めて、ターゲティングのオプションが100,000個を超えます。 | 使わなくなったオプションを削除するか、別のターゲティングを使ってください。 |
| `400` | `TARGETING_CATEGORY_LOCKED` | 広告商品で **必須含む** または **必須除外** に設定されている最上位オプション、または終了していないキャンペーンが含むか除外している最上位オプションを、オプショングループに移動しようとしました。 | 先にそれらの設定を解除してください。新しいオプションをオプショングループに入れる場合は、最初から`parent`または`children`で追加してください。[オプションの移動と切り離し](/ja/integrations/context-targeting/option-groups#オプションの移動と切り離し)を参照してください。 |
| `400` | `TARGETING_CATEGORY_NOT_SUPPORTED` | リクエストがオプションのタイプまたはオプショングループのルールに合っていません。表の下のケースを参照してください。 | リクエストを修正してください。[制約事項](/ja/integrations/context-targeting/option-groups#制約事項)を参照してください。 |
| `400` | `TARGETING_CATEGORY_TREE_ITEMS_LIMIT_EXCEEDED` | オプションの一括削除に、オプショングループと下位オプションが合わせて150個を超えて含まれています。リクエスト全体が拒否され、何も削除されません。 | IDを小さなリクエストに分割し、1件ずつ順番に送信してください。 |
| `400` | `TARGETING_COLLECTION_CONTEXT_DUPLICATED` | オプショングループ自身のコンテキストIDに追加するコンテキストIDが、すでにプロジェクト内の別のオプショングループ自身のコンテキストIDになっています。同じリクエストで作成または変更するオプショングループも対象です。 | 重複しているコンテキストIDを取り除いてください。`detail.conflicts`には、そのうち最大20件が含まれます。一意である必要があるのは、オプショングループ自身のコンテキストIDだけです。通常のオプションと下位オプションは、コンテキストIDを共有できます。 |
| `400` | `TARGETING_CONTEXT_LIMIT_EXCEEDED` | 変更によってコンテキストIDの上限を超えます。上限は、オプションあたり50,000個または8 MB、プロジェクトあたり200,000個です。 | 使わなくなったコンテキストIDを削除してください。[上限](#上限)を参照してください。 |
| `400` | `TARGETING_LOCKED` | 承認済みで終了していないキャンペーンが、ターゲティングのいずれかのオプションを含むか除外している間に、そのターゲティングを削除しようとしました。何も削除されません。 | それらのキャンペーンが終了してから、ターゲティングを削除してください。 |
| `404` | `PROJECT_NOT_FOUND` | APIキーが属するプロジェクトが、すでに存在しません。 | 存在するプロジェクトで発行したキーを使ってください。 |
| `404` | `TARGETING_CATEGORY_NOT_FOUND` | オプションが存在しないか、プロジェクトのコンテキストターゲティングにないか、`parent`が同じターゲティングのオプションではありません。成功済みの削除を再送した場合も、このコードが返されます。 | IDを確認してください。削除を再送した場合は、オプションを削除済みとして扱ってください。 |
| `404` | `TARGETING_NOT_FOUND` | ターゲティングが存在しないか、別のプロジェクトのものか、コンテキストターゲティングではありません。成功済みの削除を再送した場合も、このコードが返されます。 | IDを確認してください。削除を再送した場合は、ターゲティングを削除済みとして扱ってください。 |
| `409` | `CONTEXT_TARGETING_WRITE_IN_PROGRESS` | 同じプロジェクトで別のAPI書き込みを処理中で、リクエストの内容は何も反映されていません。`results`で返された場合は、その項目の内容が何も反映されていません。 | `detail.retryAfterMs`ミリ秒待ってから再送してください。[同時書き込み](#同時書き込み)を参照してください。 |
| `409` | `TARGETING_CATEGORY_NAME_DUPLICATE` | オプショングループと下位オプションを含め、ターゲティングにその名前のオプションがすでにあるか、リクエスト内で名前が重複しています。 | 別の名前を使ってください。作成を再送した場合は、`detail.existingIds`のIDを使ってください。 |
| `409` | `TARGETING_NAME_DUPLICATE` | オーディエンスターゲティングを含め種類を問わず、プロジェクトにその名前のターゲティングがすでにあるか、リクエスト内で名前が重複しています。 | 別の名前を使ってください。作成を再送した場合は、`detail.existingId`のIDを使ってください。 |
| `500` | `UNCATCHED` | 一括操作の`results`でのみ返されます。予期しないエラーが発生しました。作成または削除の一括リクエストでは、リクエストの内容は何も反映されていません。 | 同じリクエストを再送してください。更新の一括リクエストでは、失敗した項目を再送してください。 |

`TARGETING_CATEGORY_NOT_SUPPORTED`は、次の場合に発生します。

* オプショングループに、下位オプションも自身のコンテキストIDもない場合
* `type: "atomic"`と一緒に`children`を送信した場合、または通常のオプションに`exposeChildren`を送信した場合
* オプションの追加で、`parent`を`type: "collection"`、`children`、`exposeChildren`のいずれかと一緒に送信した場合
* `parent`が、最上位のオプショングループではないオプションを指している場合
* 更新でオプショングループに`parent`を送信した場合。オプショングループは移動できません。
* 移動、切り離し、削除によって、自身のコンテキストIDを持たないオプショングループから最後の下位オプションがなくなる場合
* 更新によって、下位オプションを持たないオプショングループのコンテキストIDがすべてなくなる場合
* [オプション一覧の取得](/ja/integrations/context-targeting/options#オプション一覧の取得)の`parent`クエリパラメータが、通常のオプションを指している場合
* オプションが、APIで変更できない形式で保存されている場合（別のオプショングループの中にあるオプショングループなど）

### detailフィールド

| フィールド | 対象のエラーコード | 説明 |
| - | - | - |
| `existingId` | `TARGETING_NAME_DUPLICATE` | その名前を持つ既存のターゲティングのID。そのターゲティングがコンテキストターゲティングの場合にのみ含まれます。 |
| `existingIds` | `TARGETING_CATEGORY_NAME_DUPLICATE` | ターゲティング内でその名前を持つ既存のオプションのID。通常は1つですが、ターゲティングにその名前のオプションがすでに複数ある場合は、複数になります。 |
| `duplicateOfIndex` | `TARGETING_NAME_DUPLICATE`、`TARGETING_CATEGORY_NAME_DUPLICATE` | 作成リクエストまたはオプションの更新リクエストの中で、名前が重複した場合に返されます。値は、その名前を最初に使った項目の`index`で、1つの項目の中で名前が重複している場合は、その項目自身の`index`になります。ターゲティング名の変更リクエストでは、前の項目の名前変更がすでに反映されているため、重複した名前には代わりに`existingId`が返されます。 |
| `retryAfterMs` | `CONTEXT_TARGETING_WRITE_IN_PROGRESS` | リクエストを再送するまでに待つ時間（ミリ秒）。0〜2,000の値です。 |
| `targeting` | `TARGETING_CATEGORY_LIMIT_EXCEEDED` | 上限を超えることになるターゲティングのID |
| `limit` | `TARGETING_CATEGORY_LIMIT_EXCEEDED`、`AD_PRODUCT_TARGETING_POLICY_LIMIT_EXCEEDED`、`TARGETING_CATEGORY_TREE_ITEMS_LIMIT_EXCEEDED` | 超えることになる上限の値 |
| `count` | `AD_PRODUCT_TARGETING_POLICY_LIMIT_EXCEEDED`、`TARGETING_CATEGORY_TREE_ITEMS_LIMIT_EXCEEDED` | 広告商品の上限の場合は、変更後の広告商品に残る必須オプションの数です。複数の広告商品が上限を超える場合は、そのうち最大の数です。一括削除の上限の場合は、リクエストに含まれるオプショングループと下位オプションの数です。 |
| `products` | `AD_PRODUCT_TARGETING_POLICY_LIMIT_EXCEEDED` | 上限を超えることになる広告商品のID |
| `conflicts` | `TARGETING_COLLECTION_CONTEXT_DUPLICATED` | 重複の一覧（最大20件）。各項目には、`value`（コンテキストID）、`collection`（もう一方のオプショングループの`_id`と`name`）、`targeting`（そのオプショングループが属するターゲティングの`_id`と`name`）が含まれます。そのオプショングループが同じリクエストで作成または変更される場合は、`collection._id`、`targeting`、`targeting.name`が含まれないことがあります。 |

***

## 一括操作のレスポンス

`POST /context-targeting/bulk/create`や`POST /context-targeting/category/bulk/update`などの一括操作のエンドポイントは、項目ごとに結果を返します。

### レスポンスのフィールド

| フィールド | タイプ | 説明 |
| - | - | - |
| `results` | object\[] | 項目ごとの結果（リクエストの順序どおり） |
| `results[].index` | number | リクエストの`items`または`ids`配列における項目の位置（0から始まる） |
| `results[].success` | boolean | 項目が成功した場合は`true` |
| `results[].data` | object | 成功した項目の結果。単一項目のエンドポイントが返すものと同じオブジェクトです。削除の場合は`_id`のみです。 |
| `results[].error` | object | 失敗した項目のエラーで、`statusCode`、`errorCode`と、一部のコードでは`detail`が含まれます。[エラーコード別のエラー](#エラーコード別のエラー)を参照してください。 |
| `succeeded` | number | 成功した項目の数 |
| `failed` | number | 失敗した項目の数 |

### レスポンスのステータス

一括リクエストが処理されると、一部またはすべての項目が失敗した場合でも`200`が返されます。`failed`、または各項目の`success`を確認してください。

次の場合は、リクエスト全体が`results`なしで失敗し、何も反映されません。

* `400`の検証エラー。たとえば、項目が多すぎる場合、コンテキストIDが合計10,000個を超える場合、オプションの一括更新に同じ`_id`が2回含まれる場合です。
* オプションの一括削除での`400 TARGETING_CATEGORY_TREE_ITEMS_LIMIT_EXCEEDED`
* `401`、`403`、`413`
* `404 PROJECT_NOT_FOUND`
* `409 CONTEXT_TARGETING_WRITE_IN_PROGRESS`

`500`または`502`のレスポンスにも`results`は含まれませんが、この場合はリクエストが反映されている場合と、反映されていない場合があります。

### 項目の反映方法

| 一括リクエスト | 項目の反映方法 |
| - | - |
| ターゲティングの作成、ターゲティングの削除、オプションの追加、オプションの削除 | 1つの単位としてまとめて反映されます。名前の重複や上限超過など、書き込み前の検査で失敗した項目はその項目だけが失敗し、ほかの項目は反映されます。予期しないエラーが発生した場合は、リクエストの内容は何も反映されません。このとき、すでに失敗していた項目にはそのエラーが返され、それ以外の項目はすべて`500 UNCATCHED`で失敗します。同じリクエストを再送してください。 |
| ターゲティング名の変更、オプションの更新 | 項目ごとに反映されます。失敗した項目はほかの項目に影響せず、成功した項目は反映されたままになります。 |

* オプションの一括更新は項目を並行して反映しますが、`results`はリクエストの順序どおりに並びます。1つのオプションへの変更は、すべて1つの項目にまとめてください。同じ`_id`が2回含まれると、リクエスト全体が拒否されます。
* 名前変更または更新のリクエストでは、前の項目が名前を変更して空けた名前を、後の項目で使えます。前の項目が失敗した場合、後の項目は名前重複エラーで失敗します。

### 例

1つ目の項目は **Sports** にコンテキストIDを追加します。2つ目の項目は **Tech** の名前を、すでに使われている **Sports** に変更しようとします。

```bash theme={null}
curl -X POST https://lake.adrop.io/context-targeting/category/bulk/update \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "_id": "01JAB3XK5RA1B2C3D4E5F6G7H8", "contexts": { "add": ["basketball"] } },
      { "_id": "01JAB3XK5RA1B2C3D4E5F6G7H9", "name": "Sports" }
    ]
  }'
```

レスポンスのステータスは`200`です。

```json theme={null}
{
  "results": [
    {
      "index": 0,
      "success": true,
      "data": {
        "_id": "01JAB3XK5RA1B2C3D4E5F6G7H8",
        "name": "Sports",
        "type": "atomic",
        "contextCount": 4,
        "createdAt": "2026-10-13T01:23:45.000Z",
        "updatedAt": "2026-10-13T02:10:00.000Z"
      }
    },
    {
      "index": 1,
      "success": false,
      "error": {
        "statusCode": 409,
        "errorCode": "TARGETING_CATEGORY_NAME_DUPLICATE",
        "detail": {
          "existingIds": ["01JAB3XK5RA1B2C3D4E5F6G7H8"]
        }
      }
    }
  ],
  "succeeded": 1,
  "failed": 1
}
```

***

## 同時書き込み

API書き込みは、プロジェクトごとに1件ずつ処理されます。対象は、単一項目か一括かを問わず、プロジェクトのどのAPIキーから送信したものも含め、コンテキストターゲティングAPIのすべての`POST`、`PATCH`、`DELETE`リクエストです。`GET`リクエストは影響を受けず、異なるプロジェクトの書き込みどうしが互いを待つこともありません。

プロジェクトで別の書き込みを処理している間に書き込みが届くと、サーバーはその処理が終わるのを少しの間待ちます。それでも処理が続いている場合、リクエストは`409 CONTEXT_TARGETING_WRITE_IN_PROGRESS`で失敗し、リクエストの内容は何も反映されません。一括リクエストは、`results`なしで全体が失敗します。

```json theme={null}
{
  "statusCode": 409,
  "errorCode": "CONTEXT_TARGETING_WRITE_IN_PROGRESS",
  "timestamp": "2026-10-13T10:23:45+09:00",
  "detail": {
    "retryAfterMs": 2000
  }
}
```

このエラーには、次のように対処します。

1. `detail.retryAfterMs`ミリ秒待ちます。値は0〜2,000です。
2. 同じリクエストを再送します。再び`409`が返された場合は、これを繰り返します。

プロジェクトへの書き込みは順番に送信してください。1つのリクエストのレスポンスを受け取ってから、次のリクエストを送信します。複数のプロセスやワーカーが同じプロジェクトに書き込む場合は、それぞれが`409`を受け取ったときに再試行するようにしてください。

<Note>
  まれに、処理が異常に長引いたリクエストの途中で、書き込みの順番が別のリクエストに移ることがあります。その場合、最初のリクエストがまだ反映していなかった項目は、`results`の中で、または単一項目のエンドポイントのレスポンスとして、同じ`409`で失敗します。このエラーになった項目は反映されていないため、それらの項目だけを再送してください。
</Note>

***

## 再試行と重複リクエスト

リクエストがタイムアウトした場合や、`502`などの`5xx`ステータスが返された場合は、リクエストが反映されたかどうかがわからないことがあります。サーバーが元のリクエストをまだ処理している可能性もあります。少し待ってから、同じリクエストを再送してください。元のリクエストがまだ処理中の場合、再送したリクエストは`409 CONTEXT_TARGETING_WRITE_IN_PROGRESS`で失敗します。少し待ってから、もう一度送信してください。

すでに成功していたリクエストを再送した場合の結果は、操作によって異なります。

| 操作 | 再送の結果 |
| - | - |
| ターゲティングの作成またはオプションの追加（単一・一括とも） | 冪等ではありません。元のリクエストで作成された項目は、それぞれ名前重複エラーで失敗し、`detail`に既存のIDが入ります。 |
| ターゲティングまたはオプションの名前変更 | 同じ結果になります。現在の名前を送ってもエラーにはなりません。 |
| `add`、`remove`、`set`によるコンテキストIDの変更 | 同じ結果になります。`add`はすでにあるコンテキストIDをスキップし、`remove`は存在しないコンテキストIDを無視します。 |
| `parent`によるオプションの移動または切り離し | 同じ結果になります。すでに指定した位置にあるオプションは、そのまま残ります。 |
| `exposeChildren`の変更 | 同じ結果になります。 |
| ターゲティングまたはオプションの削除 | `404 TARGETING_NOT_FOUND`または`TARGETING_CATEGORY_NOT_FOUND`が返されます。削除済みとして扱ってください。 |

### 作成リクエストの再送

IDは常にサーバーが生成し、作成リクエストに`_id`を含めると`400`で失敗します。すでに成功していた作成を再送した場合は、項目をもう一度作成するのではなく、`409`レスポンスに含まれるIDを使ってください。

* **ターゲティング**：`409 TARGETING_NAME_DUPLICATE`が返されます。`detail.existingId`がそのターゲティングのIDです。オプションのIDを取得するには、[ターゲティングの取得](/ja/integrations/context-targeting/targetings#ターゲティングの取得)を参照してください。
* **オプション**：`409 TARGETING_CATEGORY_NAME_DUPLICATE`が返されます。`detail.existingIds`に、その名前を持つオプションのIDが入ります。
* 一括作成では、元のリクエストで作成された項目だけがこのように失敗します。ほかの項目は通常どおり処理されます。

`detail.existingId`は、既存のターゲティングがコンテキストターゲティングの場合にのみ含まれます。オーディエンスターゲティングがその名前を使っている場合は、別の名前を選んでください。同じリクエストの中で名前が重複している場合は、代わりに`detail.duplicateOfIndex`が返されます。その場合はリクエストを修正してください。

API書き込みはプロジェクトごとに1件ずつ処理されるため、同じ作成リクエストを同時に2件送信しても、両方で作成されることはありません。後のリクエストは、名前重複エラーまたは`409 CONTEXT_TARGETING_WRITE_IN_PROGRESS`で失敗します。

### 500または502が返された場合

* 作成または削除の一括リクエストの`results`に`500 UNCATCHED`がある場合：リクエストの内容は何も反映されていません。同じリクエストを再送してください。
* 更新の一括リクエストの`results`に`500 UNCATCHED`がある場合：その項目は失敗しています。その項目を再送してください。
* `500`または`502`のレスポンスが返された場合：リクエストが反映されている場合と、反映されていない場合があります。同じリクエストを再送し、その結果を上の表に従って扱ってください。

<Note>
  `add`と`remove`の両方を含むオプションの更新が失敗した場合でも、`add`はすでに反映されていることがあります。同じ更新を再送しても問題ありません。
</Note>

***

## 上限

| 上限 | 値 | 超えた場合 |
| - | - | - |
| ターゲティングの一括リクエストあたりの項目数（作成、名前変更、削除） | 1〜100 | `400`の検証エラー |
| ターゲティングの作成リクエストあたりのオプション数（下位オプションを含む全項目の合計） | 100 | `400`の検証エラー |
| オプションの一括リクエストあたりの項目数（追加、更新、削除） | 1〜5,000 | `400`の検証エラー |
| オプションの追加リクエストあたりのオプション数（下位オプションを含む全項目の合計） | 5,000 | `400`の検証エラー |
| オプションの一括リクエストあたりのオプショングループ関連項目数。追加ではオプショングループを作成する項目と`parent`を指定した項目、更新では`parent`を指定した項目（`null`を含む）、削除ではオプショングループと下位オプションのIDが対象です。 | 150 | 追加と更新は`400`の検証エラー、削除は`400 TARGETING_CATEGORY_TREE_ITEMS_LIMIT_EXCEEDED` |
| リクエストあたりのコンテキストID数（`add`、`remove`、`set`を含む全項目の合計） | 10,000 | `400`の検証エラー |
| コンテキストIDの長さ（前後の空白を取り除いた後） | UTF-8で1〜256バイト | `400`の検証エラー |
| リクエストボディのサイズ | 8 MB | `413` |
| オプションあたりのコンテキストID数（オプショングループの場合は自身のコンテキストID） | 50,000 | `400 TARGETING_CONTEXT_LIMIT_EXCEEDED` |
| オプションのコンテキストIDの合計サイズ（オプショングループの場合は自身のコンテキストID） | 8 MB | `400 TARGETING_CONTEXT_LIMIT_EXCEEDED` |
| プロジェクトあたりのコンテキストID数（すべてのコンテキストターゲティングの全オプションの合計） | 200,000 | `400 TARGETING_CONTEXT_LIMIT_EXCEEDED` |
| ターゲティングあたりのオプション数（下位オプションを含む） | 100,000 | `400 TARGETING_CATEGORY_LIMIT_EXCEEDED` |
| 広告商品あたりの **必須含む** または **必須除外** に設定されたオプション数（すべてのターゲティングの合計） | 500 | `400 AD_PRODUCT_TARGETING_POLICY_LIMIT_EXCEEDED` |
| ターゲティング名またはオプション名の長さ | 2〜36文字 | `400`の検証エラー |
| [オプション一覧の取得](/ja/integrations/context-targeting/options#オプション一覧の取得)の`limit` | 1〜1,000（デフォルト1,000） | `400`の検証エラー |
| [オプションの取得](/ja/integrations/context-targeting/options#オプションの取得)の`limit` | 1〜10,000（デフォルト10,000） | `400`の検証エラー |
| オプションの取得の`offset` | 0〜50,000（デフォルト0） | `400`の検証エラー |
| オプショングループの`children`に含まれる下位オプションのID | 先頭の50個。合計は`childCount`で確認できます。 | — |
| `detail.conflicts`に含まれる重複 | 最大20件 | — |

* 保存データの上限（オプションあたり、プロジェクトあたり、ターゲティングあたり、広告商品あたり）は、変更によって量が増える場合にのみ確認されます。コンテキストIDの削除など量を減らす変更は、データがすでに上限を超えていてもブロックされません。
* 1回のリクエストに収まらない量をアップロードするには、これらの上限内のリクエストに分割し、1件ずつ順番に送信してください。たとえば、数万個のオプションは、1回あたり最大5,000項目のオプション一括追加リクエストに分けて追加します。
* コンテキストIDが10,000個を超えるオプションのコンテキストIDを置き換える方法は、[コンテキストIDの更新方法](/ja/integrations/context-targeting/options#コンテキストidの更新方法)を参照してください。
* リクエストボディを小さく保つため、韓国語の名前やコンテキストIDなどの非ASCII文字は、UTF-8のまま送信してください。

***

## 名前のルール

ターゲティング名とオプション名（オプショングループと下位オプションを含む）には、次のルールが適用されます。

| ルール | ターゲティング | オプション |
| - | - | - |
| 長さ | 2〜36文字 | 2〜36文字 |
| 使用できる文字 | ハングル、半角英字、半角数字、スペース、`~` `%` `&` `+` `-` | ターゲティングと同じ |
| 先頭と末尾のスペース | 使用できません。APIはスペースを取り除かずに、名前を拒否します。 | ターゲティングと同じ |
| 一意である必要がある範囲 | プロジェクト（オーディエンスターゲティングを含むすべてのターゲティング） | ターゲティング（オプショングループと下位オプションを含む） |
| 名前が無効な場合のエラー | `400`の検証エラー | `400`の検証エラー |
| 名前が重複した場合のエラー | `409 TARGETING_NAME_DUPLICATE` | `409 TARGETING_CATEGORY_NAME_DUPLICATE` |

* 日本語や中国語の文字、`_`、`.`、括弧など、それ以外の文字は使用できません。
* 1つのリクエストの中で繰り返される名前も、重複として扱われます。[detailフィールド](#detailフィールド)の`duplicateOfIndex`を参照してください。
* 現在の名前への変更は、エラーになりません。
* 異なるターゲティングのオプションには、同じ名前を付けられます。

***

## コンソールと併用する場合

* **同じデータ**：コンソールとAPIは、同じコンテキストターゲティングを管理します。APIで作成したターゲティングとオプションはコンソールに表示され、コンソールで作成したものもAPIで取得できます。
* **コンテキストターゲティングのみ**：オーディエンスターゲティングへのリクエストは`404 TARGETING_NOT_FOUND`で、そのオプションへのリクエストは`404 TARGETING_CATEGORY_NOT_FOUND`で失敗します。ただし、オーディエンスターゲティングの名前も名前の一意性の判定に含まれるため、同じ名前のコンテキストターゲティングを作成すると、`detail.existingId`のない`409 TARGETING_NAME_DUPLICATE`で失敗します。
* **コンソールでの編集は順番待ちの対象外**：1件ずつの処理が適用されるのは、API書き込みだけです。コンソールでの編集はAPI書き込みを待たず、`409 CONTEXT_TARGETING_WRITE_IN_PROGRESS`の原因にもならず、API書き込みもコンソールでの編集を待ちません。
* **同時の変更による競合**：コンソールとAPIが同じターゲティングを同時に変更すると、後から保存された変更が先の変更を上書きしたり、2つのターゲティングまたはオプションが同じ名前になったりすることがあります。自社のシステムがAPIでターゲティングに書き込んでいる間は、コンソールでそのターゲティングを編集しないでください。コンソールで変更された可能性がある場合は、書き込む前にターゲティングを取得し直してください。
* **名前の重複**：2つのターゲティングまたはオプションが同じ名前になった場合は、どちらかの名前を変更するか、どちらかを削除してください。オプションを削除する前に、[広告商品とキャンペーンへの影響](/ja/integrations/context-targeting/options#広告商品とキャンペーンへの影響)を確認してください。
* **広告商品の設定**：広告商品で **必須含む** または **必須除外** に設定するオプションを変更するには、コンソールを使用してください。[ターゲティングの販売](/ja/targeting/sell)を参照してください。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.