> ## 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キーを使って、サーバーから広告ユニットを作成・取得・更新・削除する方法をご案内します。

広告ユニットAPIを使うと、サーバーから広告ユニットを作成・管理できます。APIで作成したユニットはすぐにコンソールに表示されます。ユニットIDは、SDK連携と[広告商品API](https://docs.adrop.io/ja/integrations/ad-products.md)のクリエイティブセットに使います。

APIは、コンソールの広告ユニットと同じデータを扱います。コンソールで作成したユニットもAPIで取得・更新できます。

***

## 事前準備

* `ad-unit:read`と`ad-unit:write`のスコープを持つAPIキーが必要です。この2つのスコープは、コンソールの **\[設定]** > **\[連携]** メニューでは選択できません。Adropにご依頼いただければ、スコープを含むキーを発行します。[アプリAPI](https://docs.adrop.io/ja/integrations/apps.md)と[広告商品API](https://docs.adrop.io/ja/integrations/ad-products.md)のスコープも、同じキーにあわせて含めることができます。
* 2つのスコープは別々に確認されます。`ad-unit:write`だけのキーは、取得（`GET`）リクエストで`403`を受け取ります。作成・更新のレスポンスにはユニット全体が含まれますが、ユニットを別途取得するには`ad-unit:read`も必要です。
* ユニットを作成するアプリのIDは、[アプリAPI](https://docs.adrop.io/ja/integrations/apps.md)で取得します。

> [!WARNING]
>
> APIはサーバーからのみ呼び出してください。APIキーをアプリやウェブページに含めないでください。

***

## 基本情報

| 項目 | 値 |
| - | - |
| Base URL | `https://lake.adrop.io` |
| 認証 | `x-api-key`ヘッダーにAPIキーを指定します。キーが属するプロジェクトのユニットのみ扱えます。ほかのプロジェクトのユニットIDは`404`を返します。 |
| Content-Type | 作成・更新のリクエスト本文はJSON（`application/json`）のみ受け付けます。ほかの形式は`415`を返します。 |
| リクエスト本文の最大サイズ | 100 KB。超えると`413`を返します。取得（`GET`）リクエストに本文を含めると、サイズに関係なく`413`を返します。 |
| IDの形式 | 英数字、`_`、`-`からなる64文字以内の文字列です。新しく作成したユニットのIDは26文字のULIDです。古いユニットのIDはULIDではない場合があります。 |
| 時刻 | `createdAt`、`updatedAt`はエポックミリ秒です。 |
| 同時リクエスト | プロジェクトごとに4件まで同時に処理します。同じプロジェクトのキーを複数使っても合算し、広告商品APIとは別に数えます。超えると`429`を返します。 |

`429`を受け取ったら、`Retry-After`ヘッダーの秒数だけ待ってから再送信してください。サーバーが混雑しているときは、リクエストを1件ずつ送っても`429`を受け取ることがあります。

***

## エンドポイント

パスはBase URLを基準とします。

| メソッド | パス | スコープ | 説明 |
| - | - | - | - |
| `POST` | `/ad-units` | `ad-unit:write` | [ユニットの作成](#ユニットの作成) |
| `GET` | `/ad-units` | `ad-unit:read` | [ユニット一覧の取得](#ユニット一覧の取得) |
| `GET` | `/ad-units/{unitId}` | `ad-unit:read` | [ユニットの取得](#ユニットの取得) |
| `PATCH` | `/ad-units/{unitId}` | `ad-unit:write` | [ユニットの更新](#ユニットの更新) |
| `DELETE` | `/ad-units/{unitId}` | `ad-unit:write` | [ユニットの削除](#ユニットの削除) |

***

## ユニットの作成

新しい広告ユニットを作成します。

### リクエスト

```http theme={null}
POST /ad-units
```

`ad-unit:write`スコープが必要です。

### リクエスト本文

| フィールド | 型 | 必須 | 説明 |
| - | - | :-: | - |
| `app` | string | O | ユニットを作成するアプリのID。このプロジェクトのアプリである必要があります。 |
| `title` | string | O | ユニット名（200文字以内）。空の文字列は受け付けません。 |
| `format` | string | O | フォーマット。[フォーマットとサイズ](#フォーマットとサイズ)を参照してください。 |
| `desc` | string \| null | - | 説明（1,000文字以内） |
| `size` | object \| null | - | クリエイティブのサイズ`{ "w": 幅, "h": 高さ }`。省略するとフォーマットのデフォルトサイズを使います。`null`は画像・動画のないネイティブです。 |
| `video` | object \| null | - | 動画サイズの比率`{ "dimensions": "16:9" }`または`"9:16"`。動画サイズを使う場合にのみ指定します。 |
| `useTemplate` | boolean | - | テンプレートのみ（コンソールの表記）。プリセットサイズを使い、動画のないバナーでのみオンにできます。 |
| `useWatermark` | boolean | - | 広告マークを表示（コンソールの表記）。ネイティブでのみオンにできます。 |
| `features` | object | - | フォーマット別の設定。[フォーマット別の設定](#フォーマット別の設定)を参照してください。 |

* 省略した値は、コンソールのユニット作成画面と同じく、フォーマットごとのデフォルト値で設定されます。
* 設定をオンにして、その設定に付随する値を送らなかった場合は、コンソールと同じデフォルト値が入ります。たとえば`carouselActivated`をオンにすると、`carouselShowIndicator`と`carouselRollingInterval`がデフォルト値で設定されます。
* Webアプリには、バナーとネイティブのユニットのみ作成できます。
* レスポンスにのみあるフィールド（`_id`、`connected`、`archived`、`createdAt`、`updatedAt`）と、ここにないフィールドを送ると、`400 VALIDATION_FAILED`を返します。

### リクエスト例

```bash theme={null}
curl -X POST https://lake.adrop.io/ad-units \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "app": "01JAZ3K9Q8W5T2M4N6P7R8S9TV",
    "title": "Home Banner",
    "format": "banner",
    "size": { "w": 320, "h": 50 },
    "features": { "carouselActivated": true }
  }'
```

### レスポンス例

`201`で、作成したユニットを[ユニットオブジェクト](#ユニットオブジェクト)として返します。

```json theme={null}
{
  "_id": "01JAZ3KA1B2C3D4E5F6G7H8J9K",
  "app": "01JAZ3K9Q8W5T2M4N6P7R8S9TV",
  "title": "Home Banner",
  "format": "banner",
  "size": { "w": 320, "h": 50 },
  "useTemplate": false,
  "useWatermark": false,
  "video": null,
  "features": {
    "bgColorLight": "#FFFFFF",
    "carouselActivated": true,
    "carouselShowIndicator": true,
    "carouselRollingInterval": 3000,
    "canSupportThemeDark": false,
    "videoSupported": false,
    "videoController": false,
    "videoSkipDelayMs": 0,
    "nativeSlots": []
  },
  "connected": false,
  "archived": false,
  "createdAt": 1790820300000,
  "updatedAt": 1790820300000
}
```

> [!NOTE]
>
> 作成リクエストは冪等（idempotent）ではありません。レスポンスを受け取れずに同じリクエストを再送信すると、ユニットが重複して作成されることがあります。再送信する前に、[ユニット一覧](#ユニット一覧の取得)でユニットが作成されたか確認してください。

### エラー

* `400 AD_UNIT_VALIDATION_FAILED`: サイズ、フォーマット別の設定の範囲、設定間の条件などのユニットのルールに違反しました。
* `400 AD_UNIT_NATIVE_SLOTS_NOT_ACCEPTABLE`: `nativeSlots`がルールに合っていません。
* `404 PROJECT_APP_NOT_FOUND`: `app`がこのプロジェクトのアプリではありません。

***

## ユニットオブジェクト

取得、作成、更新のエンドポイントは、次の形式でユニットを返します。

| フィールド | 型 | 説明 |
| - | - | - |
| `_id` | string | ユニットID。SDKで広告をリクエストするときに使います。 |
| `app` | string | ユニットが属するアプリのID |
| `title` | string | ユニット名 |
| `desc` | string \| null | 説明。値がない場合は省略されるか`null`です。 |
| `format` | string | フォーマット。現在使われていないフォーマットの古いユニットには、このフィールドがありません。 |
| `size` | object \| null | クリエイティブのサイズ`{ "w", "h" }`。画像・動画のないネイティブと、一部の古いリワードユニットは`null`です。 |
| `useTemplate` | boolean | テンプレートのみを有効にしているかどうか |
| `useWatermark` | boolean | 広告マークを表示するかどうか |
| `video` | object \| null | 動画サイズの比率`{ "dimensions" }`。動画サイズでない場合と、一部の古いリワードユニットは`null`です。 |
| `features` | object | フォーマット別の設定。ユニットに保存された値のうち、そのフォーマットで使う設定だけが入っています。 |
| `connected` | boolean | SDKからこのユニットで広告がリクエストされたことがあるかどうか |
| `archived` | boolean | 削除されたユニットかどうか |
| `createdAt` | number | ユニットを作成した時刻 |
| `updatedAt` | number | ユニットを最後に更新した時刻 |

`features`は、保存されていない設定をデフォルト値で埋めて返すことはありません。

***

## フォーマットとサイズ

`format`には、次の値を大文字と小文字も含めて正確に指定します。

| `format` | コンソール | サイズのプリセット（幅x高さ） | デフォルトのサイズ |
| - | - | - | - |
| `banner` | バナー | 320x50、320x100、300x250、728x90、300x600、320x180（16:9の動画）、180x320（9:16の動画） | 300x250 |
| `native` | ネイティブ | 360x360、600x314、1200x628、320x180（16:9の動画）、180x320（9:16の動画）、画像・動画なし（`null`） | 600x314 |
| `popupBottom` | 下部ポップアップ | 360x240、360x450、320x180（16:9の動画）、180x320（9:16の動画） | 360x240 |
| `popupCenter` | 中央ポップアップ | 360x360、320x180（16:9の動画）、180x320（9:16の動画） | 360x360 |
| `interstitial` | インタースティシャル | 320x480、360x360 | 360x360 |
| `rewarded` | リワード | 180x320（9:16の動画） | 180x320 |
| `splash` | スプラッシュ | 360x270 | 360x270 |

* バナー、ネイティブ、ポップアップでは、プリセット以外のサイズを直接指定できます。幅と高さはそれぞれ1〜10,000の整数で、ポップアップは幅:高さの比率が2:3〜3:2である必要があります。
* 動画サイズ（320x180、180x320）を使う場合は、`video.dimensions`に同じ比率（`16:9`、`9:16`）を指定します。
* リワードユニットのクリエイティブは、常に9:16の動画です。

各フォーマットの特徴は[広告ユニットフォーマット](https://docs.adrop.io/ja/ad-unit/formats.md)を参照してください。

***

## フォーマット別の設定

`features`には、そのフォーマットで使う設定だけを入れられます。ほかのフォーマットの設定を入れると`400`を返します。数値はJSONの数値で送り（`"1000"`のような文字列は受け付けません）、時間の値の単位はミリ秒です。

### すべてのフォーマット

| 設定 | 型 | コンソール | 説明 |
| - | - | - | - |
| `canSupportThemeDark` | boolean | ダークモードクリエイティブを受け入れる | ダークモード用のクリエイティブを受け付けるかどうか。[ダークモード対応](https://docs.adrop.io/ja/ad-unit/dark-mode.md)を参照してください。 |
| `videoSupported` | boolean | 動画素材を受付 | バナー、ネイティブ、ポップアップでオンにできます。 |
| `videoController` | boolean | 動画コントローラー | `videoSupported`がオンの場合にのみオンにできます。 |
| `videoSkipDelayMs` | number | 動画スキップディレイ | 0〜30,000。0以外の値は、`videoController`がオンの場合にのみ指定できます。 |
| `nativeSlots` | array | メディア構成 | ネイティブユニットのメディアの一覧。下の[ネイティブのテキストとメディア](#ネイティブのテキストとメディア)を参照してください。 |

インタースティシャル、リワード、スプラッシュでは、動画の設定（`videoSupported`、`videoController`、`videoSkipDelayMs`）は常にオフです。

### バナー

| 設定 | 型 | コンソール | 説明 |
| - | - | - | - |
| `bgColorLight` | string | 背景色 | 例：`"#FFFFFF"`（32文字以内）。プリセットサイズを使い、動画のないバナーでのみ値を指定できます。 |
| `carouselActivated` | boolean | カルーセルを有効化 | 動画素材受付と同時にオンにすることはできません。 |
| `carouselShowIndicator` | boolean | インジケーターを表示 | |
| `carouselRollingInterval` | number | ローリング間隔 | 1,000〜60,000 |

### ネイティブ

| 設定 | 型 | コンソール | 説明 |
| - | - | - | - |
| `nativeShowCTA` | boolean | CTAボタン | 画像・動画のないネイティブではオンにできません。 |
| `nativeShowAdvProfileLogo` | boolean | 広告主ロゴ | |
| `nativeShowAdvProfileName` | boolean | 広告主名 | |
| `nativeTexts` | array | ネイティブテキストフィールド | 広告タイトル、広告説明などのテキスト項目の一覧。下の[ネイティブのテキストとメディア](#ネイティブのテキストとメディア)を参照してください。 |

### ポップアップ（下部・中央）

| 設定 | 型 | コンソール | 説明 |
| - | - | - | - |
| `popupTemplate` | string | ボタンテンプレート | `"performance"`（パフォーマンス最適化）または`"hideForToday"`（今日は表示しない） |
| `popupCloseButtonPosition` | number | 閉じるボタン位置 | `0`は下部の内側、`1`は上部の内側、`2`は上部の外側、`3`は下部の外側。下部ポップアップは`0`〜`2`のみ受け付けます。 |
| `popupUseDimTapToClose` | boolean | 外側タップで閉じる | |
| `popupDimOpacity` | number | 背景の不透明度 | `80`、`55`、`30`のいずれか |
| `popupUseHideUnitForToday` | boolean | 今日は表示しないボタン | |
| `popupUseHideCampaignForToday` | boolean | この広告を今日は表示しない | |
| `carouselCountLimit` | number \| null | 最大広告数 | 1〜20。`null`の場合は数の制限をオフにします。 |

### インタースティシャル

| 設定 | 型 | コンソール | 説明 |
| - | - | - | - |
| `interstitialCloseDelayTime` | number | 閉じるボタン遅延 | 0〜10,000 |

### スプラッシュ

| 設定 | 型 | コンソール | 説明 |
| - | - | - | - |
| `bgColorLight` | string | 背景色 | 例：`"#FFFFFF"`（32文字以内） |
| `splashCloseTime` | number | スプラッシュ表示時間 | 500〜3,000 |

リワードでは、すべてのフォーマットに共通の設定のみを使います。

### 設定の条件

* テンプレートのみ（`useTemplate`）は、プリセットサイズを使い、動画のないバナーでのみオンにできます。
* `canSupportThemeDark`は、テンプレートのみをオンにしていないバナー、画像・動画のあるネイティブ、ポップアップ、スプラッシュでのみオンにできます。
* 画像・動画のないネイティブでは、**広告マークを表示**（`useWatermark`）、**CTAボタン**、**動画素材を受付**をオンにできません。
* 範囲は、その設定がオンの場合にのみ確認します。たとえば`carouselRollingInterval`は、`carouselActivated`がオンの場合に確認します。

### ネイティブのテキストとメディア

* `nativeTexts`の項目は、`id`（英小文字、数字、`_`）、`label`、`maxLength`（0より大きい最大文字数）、`optional`（任意項目かどうか）で構成されます。最大50個まで入れられます。
* `headline`（広告タイトル）と`body`（広告説明）は、`nativeTexts`の1番目か2番目にのみ置けます。
* `nativeSlots`の項目は`id`、`label`（任意）、`w`、`h`で構成され、画像・動画のあるネイティブでのみ使えます。1番目のメディアの`id`は`m1`で、サイズはユニットの`size`と同じである必要があります。最大3個まで入れられ、メディアが1つだけの場合は`[]`として保存されます。
* `id`は、`nativeTexts`と`nativeSlots`のすべてを通して重複できません。

`nativeSlots`のルールに違反すると`400 AD_UNIT_NATIVE_SLOTS_NOT_ACCEPTABLE`を返し、`detail.reason`で理由を知らせます。複数メディアについては[ネイティブの複数メディア](https://docs.adrop.io/ja/ad-unit/native-multi-media.md)を参照してください。

***

## ユニット一覧の取得

プロジェクトのユニットを新しい順に、ページ単位で返します。デフォルトでは、削除されたユニットは含まれません。

### リクエスト

```http theme={null}
GET /ad-units
```

`ad-unit:read`スコープが必要です。

### クエリパラメーター

| パラメーター | 型 | 必須 | デフォルト値 | 説明 |
| - | - | :-: | - | - |
| `limit` | number | - | `20` | 1回で受け取るユニットの数（1〜120） |
| `next` | string | - | - | 次のページのカーソル。前のレスポンスの`next`をそのまま入れます。最初のページでは省略します。 |
| `format` | string | - | - | このフォーマットのユニットだけを受け取ります（例：`splash`）。省略するとすべてのフォーマットが対象です。 |
| `includeArchived` | boolean | - | `false` | `true`の場合は、削除されたユニットも含めます。 |

### リクエスト例

```bash theme={null}
curl "https://lake.adrop.io/ad-units?format=banner&limit=20" \
  -H "x-api-key: YOUR_API_KEY"
```

### レスポンス例

`200`で、`items`（ユニットの一覧）と`next`（次のページのカーソル）を返します。`next`がなければ最後のページです。

```json theme={null}
{
  "items": [
    {
      "_id": "01JAZ3KA1B2C3D4E5F6G7H8J9K",
      "app": "01JAZ3K9Q8W5T2M4N6P7R8S9TV",
      "title": "Home Banner",
      "format": "banner",
      "size": { "w": 320, "h": 50 },
      "useTemplate": false,
      "useWatermark": false,
      "video": null,
      "features": { "bgColorLight": "#FFFFFF", "carouselActivated": false, "videoSupported": false },
      "connected": true,
      "archived": false,
      "createdAt": 1790820300000,
      "updatedAt": 1790820300000
    }
  ],
  "next": "01JAZ3KA1B2C3D4E5F6G7H8J9K"
}
```

並び順はおおむね作成の新しい順ですが、古いユニットは順序が異なる場合があります。順序に頼らず、`next`で続きを読み込んでください。

***

## ユニットの取得

1つのユニットを返します。削除されたユニットもIDで取得でき、その場合`archived`は`true`です。

### リクエスト

```http theme={null}
GET /ad-units/{unitId}
```

`ad-unit:read`スコープが必要です。

### リクエスト例

```bash theme={null}
curl "https://lake.adrop.io/ad-units/01JAZ3KA1B2C3D4E5F6G7H8J9K" \
  -H "x-api-key: YOUR_API_KEY"
```

### レスポンス

`200`で[ユニットオブジェクト](#ユニットオブジェクト)を返します。

### エラー

* `404 AD_UNIT_NOT_FOUND`: ユニットが存在しないか、ほかのプロジェクトのユニットです。

***

## ユニットの更新

送ったフィールドだけを変更します。

### リクエスト

```http theme={null}
PATCH /ad-units/{unitId}
```

`ad-unit:write`スコープが必要です。リクエスト本文は、[ユニットの作成](#リクエスト本文)のフィールドから`app`を除いたものと同じです。ユニットのアプリは変更できません。

### クエリパラメーター

| パラメーター | 型 | 必須 | 説明 |
| - | - | :-: | - |
| `ifUpdatedAt` | number | - | 最後に取得したユニットの`updatedAt`。その後にユニットが変更されていれば`409 AD_UNIT_CONFLICT`を返し、何も変更しません。 |

### 変更のされ方

* 送らなかったフィールドはそのままです。空の本文`{}`を送っても何も変わりません。
* `features`は、送った設定だけが変わり、残りの設定はそのままです。ただし、`carouselActivated`、`videoSupported`、`videoController`をオン・オフすると、一緒に送らなかった従属する設定（`carouselShowIndicator`、`carouselRollingInterval`、`videoController`、`videoSkipDelayMs`）は、オンにしたときは既定値に、オフにしたときはオフの値に変わります。
* `null`を送れるのは、`desc`（説明の削除）、`size`（画像・動画のないネイティブへの変更）、`video`（動画サイズの解除）、`features.carouselCountLimit`（ポップアップのカルーセル数の制限をオフにする）だけです。
* フォーマットを変更するときに、現在のサイズが新しいフォーマットのプリセットでない場合は、`size`も一緒に送る必要があります。新しいフォーマットで使わない設定は削除され、新しいフォーマットの設定はデフォルト値で設定されます。
* 削除されたユニットは更新できません（`409 AD_UNIT_ARCHIVED`）。

### 変更できないフィールド

SDKから広告がリクエストされたことのあるユニット（`connected: true`）と、広告商品のクリエイティブセットに含まれているユニットは、`format`、`size`、`video`、`nativeSlots`の`id`を変更できません（`409 AD_UNIT_FIELD_LOCKED`）。名前、説明、その他の設定は変更できます。

### 広告商品への影響

広告商品に含まれているユニットの`useTemplate`、`useWatermark`、`features`を変更すると、クリエイティブセットの基準に合わなくなることがあります。その場合、そのユニットはその商品で **修正必要** ステータス（`fixRequired`）になり、広告が配信されません。詳しくは[広告商品APIのクリエイティブセット](https://docs.adrop.io/ja/integrations/ad-products.md#クリエイティブセット)を参照してください。

このユニットを使う商品が多すぎて一度に再調整できない場合は、`409 AD_UNIT_RECONCILE_LIMIT_EXCEEDED`を返し、何も変更しません。`detail.limit`には超えた上限の名前が、`detail.max`にはその上限値が入っています。

> [!TIP]
>
> ユニットを取得したレスポンスから、レスポンスにのみあるフィールド（`_id`、`app`、`connected`、`archived`、`createdAt`、`updatedAt`）を除いてそのまま送ると、何も変わりません。かなり前にコンソールで作成したユニットは、`features`の数値が文字列（例：`"1000"`）で保存されていることがあるため、送り直すときは数値に変換して送ってください。

### リクエスト例

```bash theme={null}
curl -X PATCH "https://lake.adrop.io/ad-units/01JAZ3KA1B2C3D4E5F6G7H8J9K?ifUpdatedAt=1790820300000" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Home Banner (Main)",
    "features": { "carouselRollingInterval": 5000 }
  }'
```

### レスポンス

`200`で、更新した[ユニットオブジェクト](#ユニットオブジェクト)を返します。

### エラー

* `404 AD_UNIT_NOT_FOUND`: ユニットが存在しないか、ほかのプロジェクトのユニットです。
* `409 AD_UNIT_ARCHIVED`: 削除されたユニットです。
* `409 AD_UNIT_CONFLICT`: `ifUpdatedAt`がユニットの`updatedAt`と異なります。ユニットを取得し直してから更新してください。
* `409 AD_UNIT_FIELD_LOCKED`: 変更できないフィールドを変更しようとしました。
* `409 AD_UNIT_RECONCILE_LIMIT_EXCEEDED`: このユニットを使う商品が多すぎます。

***

## ユニットの削除

ユニットを削除します。削除したユニットは元に戻せません。

### リクエスト

```http theme={null}
DELETE /ad-units/{unitId}
```

`ad-unit:write`スコープが必要です。

### リクエスト例

```bash theme={null}
curl -X DELETE "https://lake.adrop.io/ad-units/01JAZ3KA1B2C3D4E5F6G7H8J9K" \
  -H "x-api-key: YOUR_API_KEY"
```

### レスポンス例

`200`で、ユニットIDを返します。

```json theme={null}
{ "_id": "01JAZ3KA1B2C3D4E5F6G7H8J9K" }
```

* 削除したユニットは一覧に表示されなくなりますが、IDでは引き続き取得できます（`archived: true`）。すでに削除したユニットをもう一度削除しても`200`を返します。
* 削除したユニットは、このユニットを使うすべての広告商品のクリエイティブセットから外れます。空になったクリエイティブセットも一緒に削除されるため、ユニットが1つもない商品が残ることがあります。

> [!WARNING]
>
> 削除する前に、[広告商品API](https://docs.adrop.io/ja/integrations/ad-products.md#商品の取得)でこのユニットを使う商品があるか確認してください。商品一覧にはユニットIDが含まれないため、商品ごとに取得して`unitGroups[].units`を確認します。

### エラー

* `404 AD_UNIT_NOT_FOUND`: ユニットが存在しないか、ほかのプロジェクトのユニットです。
* `409 AD_UNIT_RECONCILE_LIMIT_EXCEEDED`: このユニットを使う商品が多すぎます。先に商品からこのユニットを外してください。

***

## エラー処理

### エラーレスポンス

エラーレスポンスには`statusCode`が含まれ、下の表で`errorCode`の欄が`-`ではないエラーには`errorCode`も含まれます。リクエストのどの部分が誤っているかを知らせるエラーは、`detail`も一緒に返します。処理は`errorCode`で分け、`errorCode`がない場合は`statusCode`で分けてください。

```json theme={null}
{
  "statusCode": 400,
  "errorCode": "AD_UNIT_VALIDATION_FAILED",
  "timestamp": "2026-11-05T19:58:22+09:00",
  "detail": {
    "errors": [
      {
        "path": "features.splashCloseTime",
        "constraint": "max",
        "message": "features.splashCloseTime must not be greater than 3000",
        "value": 5000
      }
    ]
  }
}
```

`detail.errors[]`の`path`は誤ったフィールドの位置で、`value`は送った値です。`detail.errors`には最大100件まで含まれます。リクエスト形式のエラー（`VALIDATION_FAILED`）には`message`と`error`フィールドも含まれますが、`features`のエラーは`message`では1行にまとめられるため、設定ごとのエラーは`detail.errors[]`で確認してください。

### エラーコード

| ステータス | `errorCode` | 原因 |
| - | - | - |
| `400` | `VALIDATION_FAILED` | リクエストの形式が誤っています。不明なフィールドやレスポンスにのみあるフィールドを送ったか、値の型・形式・長さが合っていないか、`format`がフォーマット名ではないか、JSONの文法が誤っています。 |
| `400` | `AD_UNIT_VALIDATION_FAILED` | ユニットのルールに違反しました。サイズ、動画、アプリのプラットフォーム、フォーマット別の設定の範囲と条件などが該当します。 |
| `400` | `AD_UNIT_NATIVE_SLOTS_NOT_ACCEPTABLE` | `nativeSlots`がルールに合っていません。`detail.reason`に理由が入っています。 |
| `401` | - | APIキーがない、誤っている、または廃棄されています。 |
| `403` | - | 必要なスコープ（`ad-unit:read`または`ad-unit:write`）がありません。 |
| `404` | `AD_UNIT_NOT_FOUND` | ユニットが存在しないか、ほかのプロジェクトのユニットです。 |
| `404` | `PROJECT_APP_NOT_FOUND` | ユニットの作成時に送った`app`が、このプロジェクトのアプリではありません。 |
| `408` | `REQUEST_BODY_TIMEOUT` | リクエスト本文を30秒以内に送りきれなかったか、毎秒16 KBより遅く送りました。 |
| `409` | `AD_UNIT_FIELD_LOCKED` | SDKから広告がリクエストされたことのあるユニット、または商品に含まれているユニットの`format`、`size`、`video`、`nativeSlots`の`id`を変更しようとしました。 |
| `409` | `AD_UNIT_CONFLICT` | `ifUpdatedAt`がユニットの`updatedAt`と異なります。 |
| `409` | `AD_UNIT_ARCHIVED` | 削除されたユニットを更新しようとしました。 |
| `409` | `AD_UNIT_RECONCILE_LIMIT_EXCEEDED` | このユニットを使う商品が多すぎて処理できません。 |
| `413` | - | リクエスト本文が100 KBを超えているか、取得リクエストに本文を含めました。 |
| `415` | `UNSUPPORTED_MEDIA_TYPE` | リクエスト本文がJSONではないか、対応していない文字エンコーディングです。UTF-8を使ってください。 |
| `429` | `TOO_MANY_CONCURRENT_REQUESTS` | 同時リクエストの上限を超えたか、サーバーが混雑しています。`Retry-After`ヘッダーの秒数だけ待ってから再送信してください。 |
| `502` | - | サーバー内部の通信に問題があります。 |

### 再送信

* 書き込みリクエスト（`POST`、`PATCH`、`DELETE`）が`502`を受け取ったか、レスポンスなしで切断された場合は、リクエストが反映されている可能性があります。再送信する前にユニットを取得して確認してください。作成リクエストは冪等ではないため、そのまま再送信するとユニットが重複して作成されることがあります。
* `ifUpdatedAt`を付けた更新リクエストを再送信する場合、前のリクエストが反映されていると`409 AD_UNIT_CONFLICT`を受け取ることがあります。ユニットを取得し直して確認してください。

***

## 上限

| 項目 | 上限 |
| - | - |
| ユニット名 | 200文字 |
| 説明 | 1,000文字 |
| 直接指定するサイズ | 幅・高さそれぞれ1〜10,000 |
| `nativeTexts` | 50個（`id`は64文字、`label`は500文字） |
| `nativeSlots` | 3個（`id`は64文字、`label`は500文字） |
| `bgColorLight` | 32文字 |
| リクエスト本文 | 100 KB |
| 同時リクエスト | プロジェクトあたり4件 |
| リクエスト本文の送信 | 30秒以内、毎秒16 KB以上 |
| レスポンスの受信 | 30秒以内にレスポンスを受け取りきれないと、サーバーが接続を切断します。 |


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