> ## 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/ko/integrations/ad-products.md)의 소재 세트에 사용합니다.

API는 콘솔의 광고 유닛과 같은 데이터를 다룹니다. 콘솔에서 만든 유닛도 API로 조회하고 수정할 수 있습니다.

***

## 사전 준비

* `ad-unit:read`와 `ad-unit:write` 권한(scope)이 있는 API 키가 필요합니다. 이 두 권한은 콘솔 **\[관리]** > **\[연동]** 메뉴에서 선택할 수 없습니다. 에이드랍에 요청하면 권한을 넣은 키를 발급해 드리며, [앱 API](https://docs.adrop.io/ko/integrations/apps.md)와 [광고 상품 API](https://docs.adrop.io/ko/integrations/ad-products.md) 권한도 같은 키에 함께 받을 수 있습니다.
* 두 권한은 따로 확인합니다. `ad-unit:write`만 있는 키는 조회(`GET`) 요청에서 `403`을 받습니다. 만들기·수정 응답에는 유닛 전체가 담기지만, 유닛을 따로 조회하려면 `ad-unit:read`도 필요합니다.
* 유닛을 만들 앱의 ID는 [앱 API](https://docs.adrop.io/ko/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이고, 오래된 유닛은 ULID가 아닌 ID일 수 있습니다. |
| 시각 | `createdAt`, `updatedAt`은 epoch 밀리초입니다. |
| 동시 요청 | 프로젝트당 4건까지 동시에 처리합니다. 같은 프로젝트의 키를 여러 개 써도 합쳐서 세며, 광고 상품 API와는 따로 셉니다. 넘으면 `429`를 반환합니다. |

`429`를 받으면 `Retry-After` 헤더에 적힌 시간(초)만큼 기다린 뒤 다시 보내세요. 서버가 바쁠 때는 요청을 하나씩 보내도 `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 | - | AD 마크 표시(콘솔 표기). 네이티브만 켤 수 있습니다. |
| `features` | object | - | 포맷별 설정. [포맷별 설정](#포맷별-설정)을 참고하세요. |

* 생략한 값은 콘솔 유닛 만들기 화면과 같은 포맷별 기본값으로 채워집니다.
* 설정을 켜고 딸린 값을 보내지 않으면 콘솔과 같은 기본값이 들어갑니다. 예를 들어 `carouselActivated`를 켜면 `carouselShowIndicator`와 `carouselRollingInterval`이 기본값으로 채워집니다.
* 웹 앱에는 배너와 네이티브 유닛만 만들 수 있습니다.
* 응답에만 있는 필드(`_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 | AD 마크 표시 여부 |
| `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/ko/ad-unit/formats.md)을 참고하세요.

***

## 포맷별 설정

`features`에는 포맷이 쓰는 설정만 넣을 수 있습니다. 다른 포맷의 설정을 넣으면 `400`을 반환합니다. 숫자는 JSON 숫자로 보내고(`"1000"` 같은 문자열은 받지 않습니다), 시간 값의 단위는 밀리초입니다.

### 모든 포맷

| 설정 | 타입 | 콘솔 | 설명 |
| - | - | - | - |
| `canSupportThemeDark` | boolean | 다크 모드 소재 받기 | 다크 모드용 소재를 받을지 여부. [다크 모드](https://docs.adrop.io/ko/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`는 템플릿만 허용을 켜지 않은 배너, 이미지·동영상이 있는 네이티브, 팝업, 스플래시에서만 켤 수 있습니다.
* 이미지·동영상이 없는 네이티브는 AD 마크 표시(`useWatermark`), CTA 버튼, 동영상 소재 받기를 켤 수 없습니다.
* 범위는 해당 설정이 켜져 있을 때만 검사합니다. 예를 들어 `carouselRollingInterval`은 `carouselActivated`가 켜져 있을 때 검사합니다.

### 네이티브 텍스트와 미디어

* `nativeTexts` 항목은 `id`(영문 소문자, 숫자, `_`), `label`, `maxLength`(0보다 큰 최대 글자 수), `optional`(선택 항목 여부)로 이루어집니다. 최대 50개까지 넣을 수 있습니다.
* `headline`(광고 제목)과 `body`(광고 설명)는 `nativeTexts`의 첫 번째나 두 번째 자리에만 둘 수 있습니다.
* `nativeSlots` 항목은 `id`, `label`(선택), `w`, `h`로 이루어지며, 이미지·동영상이 있는 네이티브에서만 쓸 수 있습니다. 첫 번째 미디어의 `id`는 `m1`이고 사이즈는 유닛의 `size`와 같아야 합니다. 최대 3개까지 넣을 수 있으며, 미디어가 하나뿐이면 `[]`로 저장됩니다.
* `nativeTexts`와 `nativeSlots`의 `id`는 모두 합쳐 겹칠 수 없습니다.

`nativeSlots` 규칙을 어기면 `400 AD_UNIT_NATIVE_SLOTS_NOT_ACCEPTABLE`을 반환하고 `detail.reason`에 이유를 알려 줍니다. 다중 미디어는 [네이티브 다중 미디어](https://docs.adrop.io/ko/ad-unit/native-multi-media.md)를 참고하세요.

***

## 유닛 목록 조회

프로젝트의 유닛을 최신 순으로 페이지 단위로 반환합니다. 기본으로 삭제된 유닛은 빠집니다.

### 요청

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

`ad-unit:read` 권한이 필요합니다.

### 쿼리 파라미터

| 파라미터 | 타입 | 필수 | 기본값 | 설명 |
| - | - | :-: | - | - |
| `limit` | number | - | `20` | 한 번에 받을 유닛 수(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`로 이어서 읽으세요.

***

## 유닛 조회

유닛 하나를 반환합니다. 삭제된 유닛도 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/ko/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`을 반환합니다.
* 삭제한 유닛은 이 유닛을 쓰는 모든 광고 상품의 소재 세트에서 빠집니다. 비게 된 소재 세트도 함께 없어지므로 유닛이 하나도 없는 상품이 남을 수 있습니다.

> [!WARNING]
>
> 삭제하기 전에 [광고 상품 API](https://docs.adrop.io/ko/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`에 한 줄로 합쳐지므로 설정별 오류는 `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.