> ## 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.

# Ad Product API

> Learn how to create, read, update, and delete ad products from your server with an API key.

The Ad Product API lets you create and manage ad products from your server. Use it to automate product creation you'd otherwise do in the console, or to keep Adrop ad products in sync with the products in your own sales system.

The API works on the same data as ad products in the console. Products you create with the API appear in the console product list right away and are sold the same way as products created in the console. You can also read and update products created in the console.

***

## Prerequisites

* You need an API key with the `ad-product:read` and `ad-product:write` scopes. You can't select these scopes in **\[Settings]** > **\[Integrations]** in the console. Ask Adrop, and we'll issue you a key with both scopes. You can get the [App API](https://docs.adrop.io/integrations/apps.md), [Ad Unit API](https://docs.adrop.io/integrations/ad-units.md), and [Audience Targeting API](https://docs.adrop.io/integrations/audience-targeting.md) scopes on the same key.
* The two scopes are checked separately. A key with only `ad-product:write` gets `403` on read (`GET`) requests. Create, update, and restore responses include the full product, but you also need `ad-product:read` to read products separately.
* Get the ad unit IDs to put in a product with the [Ad Unit API](https://docs.adrop.io/integrations/ad-units.md), or find them in the **Ad Units** menu in the console. Look up targeting IDs and targeting option IDs with the [Audience Targeting API](https://docs.adrop.io/integrations/audience-targeting.md) and the [Context Targeting API](https://docs.adrop.io/integrations/context-targeting/overview.md).

> [!WARNING]
>
> Call the API from your server only. Don't put API keys in apps or web pages.

***

## Basics

| Item | Value |
| - | - |
| Base URL | `https://lake.adrop.io` |
| Authentication | Put the API key in the `x-api-key` header. You can only work with products in the key's project. Product IDs from other projects return `404`. |
| Content-Type | Create and update request bodies must be JSON (`application/json`). Other types return `415`. |
| Maximum request body size | 8 MB. Larger bodies return `413`. A read (`GET`) request with a body returns `413` regardless of its size. |
| ID format | A string of up to 64 letters, digits, `_`, and `-`. New products get a 26-character ULID. |
| Timestamps | `createdAt`, `updatedAt`, and `deleteAt` are epoch milliseconds. |
| Concurrent requests | Up to 4 per project at a time, counted across all keys of the same project. More return `429`. |

When you get `429`, wait for the number of seconds in the `Retry-After` header, then send the request again. When the server is busy, you can get `429` even if you send requests one at a time. For all request limits, see [Limits](#limits).

***

## Endpoints

Paths are relative to the Base URL.

| Method | Path | Scope | Description |
| - | - | - | - |
| `POST` | `/ad-products` | `ad-product:write` | [Create a product](#create-a-product) |
| `GET` | `/ad-products` | `ad-product:read` | [List products](#list-products) |
| `GET` | `/ad-products/{productId}` | `ad-product:read` | [Get a product](#get-a-product) (with targeting policies) |
| `PATCH` | `/ad-products/{productId}` | `ad-product:write` | [Update a product](#update-a-product) |
| `DELETE` | `/ad-products/{productId}` | `ad-product:write` | [Delete a product](#delete-a-product) (scheduled deletion) |
| `POST` | `/ad-products/{productId}/restore` | `ad-product:write` | [Restore a product](#restore-a-product) |

***

## Create a Product

Creates an ad product.

### Request

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

Requires the `ad-product:write` scope. For the fields you can send, see [Request Body](#request-body).

### Required Fields

| Field | Required when | Description |
| - | - | - |
| `title` | Always | Ad product name. An empty string isn't accepted. |
| `pricing.pricingType` | Always | Billing type: `CPM`, `CPC`, `CPP`, or `INHOUSE` (in-house) |
| `unitGroups` | Always | Creative sets. At least one creative set must contain an ad unit. See [Creative Sets](#creative-sets). |
| `pricing.price` | Not in-house | Unit price greater than 0 |
| `metric.eImpressions` | Not in-house | Daily impressions greater than 0 |
| `metric.eCTR` | Not in-house | Expected CTR. You can omit it if all units are splash units. |
| `options.cppSlots`, `options.cppMinDays` | CPP | Slots (integer 1–50) and minimum period (integer 1–150 days) |
| `locale.currency` | Not in-house, and the project has no currency | One of `KRW`, `USD`, `JPY`, and `INR`. If the project has a currency, omitting it uses that currency. |

Omitted fields get these defaults.

| Field | Default |
| - | - |
| `private` | `false` |
| `frequency` | `50` |
| `minBudget` | `0` |
| `discountRate` | `0` |
| `locale` | The project's country, currency, time zone, and language |

For an in-house product, you only need to send `title`, `pricing.pricingType: "INHOUSE"`, and `unitGroups`. The other values, such as private (`private: true`) and a unit price, product discount rate, and minimum budget of 0, are set automatically. If you send these fields, you can only send the values that are set automatically. Other values return `400`.

### Request Example

```bash theme={null}
curl -X POST https://lake.adrop.io/ad-products \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Home Banner CPM",
    "pricing": { "pricingType": "CPM", "price": 3000 },
    "metric": { "eImpressions": 100000, "eCTR": 1.5 },
    "unitGroups": [
      { "name": "Home Banner", "units": ["01JAZ3KA1B2C3D4E5F6G7H8J9K"] }
    ],
    "targetings": [
      {
        "targeting": "01JAZ3K9Q8W5T2M4N6P7R8S9TV",
        "surchargeRate": 15,
        "policies": {
          "01JAZ3KC3D4E5F6G7H8J9K0M1N": { "policy": "included" },
          "01JAZ3KD4E5F6G7H8J9K0M1N2P": { "policy": "any" }
        }
      }
    ]
  }'
```

### Response Example

Returns `201` with the new product as a [product object](#product-object).

```json theme={null}
{
  "_id": "01JAZ3KB2C3D4E5F6G7H8J9K0M",
  "title": "Home Banner CPM",
  "private": false,
  "pricing": { "pricingType": "CPM", "price": 3000 },
  "discountRate": 0,
  "minBudget": 0,
  "frequency": 50,
  "metric": { "eImpressions": 100000, "eCTR": 1.5 },
  "options": {},
  "locale": { "country": "KR", "currency": "KRW", "timezone": "Asia/Seoul", "language": "ko" },
  "unitGroups": [
    { "name": "Home Banner", "units": ["01JAZ3KA1B2C3D4E5F6G7H8J9K"], "fixRequired": [] }
  ],
  "targetings": [
    {
      "targeting": "01JAZ3K9Q8W5T2M4N6P7R8S9TV",
      "kind": "audience",
      "surchargeRate": 15,
      "policies": {
        "01JAZ3KC3D4E5F6G7H8J9K0M1N": { "policy": "included" },
        "01JAZ3KD4E5F6G7H8J9K0M1N2P": { "policy": "any" }
      }
    }
  ],
  "createdAt": 1790820300000,
  "updatedAt": 1790820300000
}
```

> [!NOTE]
>
> Create requests aren't idempotent. If you resend a request because you didn't get a response, the product can be created twice. Before resending, check the [product list](#list-products) to see whether the product was created.

### Errors

* `400`: The request body doesn't follow the [product rules](#product-rules). See [Error Handling](#error-handling).
* `409 AD_PRODUCT_LIMIT_EXCEEDED`: The project already has 1,000 products. Products scheduled for deletion count too.

***

## Product Object

The get, create, update, and restore endpoints return products in this format. [List products](#list-products) returns only part of it.

| Field | Type | Description |
| - | - | - |
| `_id` | string | Product ID |
| `title` | string \| null | Ad product name. Older products may have no value or `null`. |
| `guide` | string \| null | Creative guide link (an `http` or `https` URL). Omitted or `null` when there's no value. |
| `private` | boolean | Whether the product is private |
| `pricing.pricingType` | string | Billing type: `CPM`, `CPC`, `CPP`, or `INHOUSE` (in-house). Products with a billing type that's no longer used don't have this field. |
| `pricing.price` | number | Unit price in the `locale.currency` currency: per 1,000 impressions for CPM, per click for CPC, and per day for CPP. 0 for in-house. |
| `discountRate` | number | Product discount rate in percent (`10` = 10%). Only on products that have a stored value. |
| `minBudget` | number | Minimum budget in the `locale.currency` currency. Only on products that have a stored value. |
| `frequency` | number | Frequency cap: the most times one campaign can be shown to one user per day. `0` for products set to **No limit** in the console. Only on products that have a stored value. |
| `metric.eImpressions` | number | Daily impressions |
| `metric.eCTR` | number | Expected CTR in percent (`1.5` = 1.5%) |
| `options.cppSlots` | number | Slots. On CPP products. |
| `options.cppMinDays` | number | Minimum period in days. On CPP products. |
| `locale` | object | The product's `country`, `currency`, `timezone`, and `language` |
| `unitGroups` | object\[] | Creative sets. Each item has `name` (creative set name), `units` (all unit IDs), and `fixRequired` (the unit IDs among them that need modification). See [Creative Sets](#creative-sets). |
| `targetings` | object\[] | Targetings shown on the product. Each item has `targeting` (targeting ID), `kind` (`audience` or `context`), `surchargeRate` (premium rate in percent), and `policies` (policy per option). See [Targeting Policies](#targeting-policies). |
| `deleteAt` | number | Scheduled deletion time. Only on products scheduled for deletion. See [Delete a product](#delete-a-product). |
| `createdAt` | number | When the product was created |
| `updatedAt` | number | When the product was last updated |

* `discountRate`, `minBudget`, and `frequency` aren't filled with 0 when there's no value. If a field has no value, don't send it in updates either. Sending `0` for `frequency` sets the product to no limit.
* Product options you can only set in the console aren't in the response. They stay as they are when you update the product with the API.
* In-house products are fixed to `private: true`, `0` for `price`, `discountRate`, `minBudget`, and `metric.eCTR`, and `9007199254740991` for `metric.eImpressions`.

***

## Request Body

Create and update request bodies can include these fields. Fields not listed here and fields that only appear in responses (`_id`, `createdAt`, `updatedAt`, `deleteAt`, `unitGroups[].fixRequired`, `targetings[].kind`) return `400 VALIDATION_FAILED`.

| Field | Type | Description |
| - | - | - |
| `title` | string | Ad product name (up to 200 characters) |
| `guide` | string \| null | Creative guide link (up to 2,048 characters). Send `null` to clear it. `guide` is the only field that accepts `null`. |
| `private` | boolean | Whether the product is private |
| `pricing` | object | `pricingType` (`CPM`, `CPC`, `CPP`, or `INHOUSE`, case-sensitive) and `price` |
| `discountRate` | number | Product discount rate in percent |
| `minBudget` | number | Minimum budget |
| `frequency` | number | Frequency cap (integer 0–999). `0` means no limit. |
| `metric` | object | `eImpressions` (daily impressions) and `eCTR` (expected CTR in percent) |
| `options` | object | `cppSlots` (slots) and `cppMinDays` (minimum period). Used by CPP products only. |
| `locale` | object | Only `currency` can be sent. You can't change the country, time zone, or language. |
| `unitGroups` | object\[] | Creative sets. Each item has `name` and `units`. |
| `targetings` | object\[] | Targetings. Each item has `targeting`, `surchargeRate`, and `policies`. |

### Product Rules

Request bodies are checked against the product rules below. When a rule is broken, the API returns `400 AD_PRODUCT_VALIDATION_FAILED` and lists what's wrong in `detail.errors`. An empty ad product name or an unknown billing type returns a request format error (`400 VALIDATION_FAILED`) instead.

| Item | Rule |
| - | - |
| Billing type | One of `CPM`, `CPC`, `CPP`, and `INHOUSE`. Products with only splash units can't be CPC. |
| Unit price | Greater than 0 unless in-house. KRW and JPY take integers, and USD and INR take up to 2 decimal places. The price after discounts and premiums must also be greater than 0. |
| Product discount rate | 0 or more, below 100 |
| Premium rate | 0 or more per targeting, with no upper limit. 0 for CPP and in-house products. |
| Minimum budget | 0, or at least the unit price. 0 for CPP and in-house products. |
| Daily impressions | Greater than 0 |
| Expected CTR | 0–100. Greater than 0 for CPC products. |
| Slots, minimum period | Required for CPP products. Integer 1–50 and integer 1–150. |
| Frequency cap | Integer 0–999. `0` means no limit. |
| Creative guide link | An `http` or `https` URL |
| Ad product name | Can't be empty |
| In-house | Values that differ from the automatically set values return `400`. |

### Creative Sets

Each item in `unitGroups` is one creative set in the console. `name` is the creative set name shown to advertisers, and `units` is the list of ad unit IDs in the set.

* All units in a creative set must have the same format, size, and options (template, watermark, and so on). If a unit you add doesn't match the set, the API returns `400 AD_UNIT_FIX_REQUIRED`. For the criteria, see [Configure Creative Sets](https://docs.adrop.io/ad-product/create.md#step-2-configure-creative-sets).
* Each unit ID can appear only once across all creative sets.
* Creative sets with the same format, size, and options can't have the same name.
* A new creative set must contain at least one unit.
* The product must keep at least one unit that matches its creative set. Units that need modification don't count.

`fixRequired` lists units whose format, size, or options changed after they were added, so they no longer match the creative set. This is the same as the **Needs Modification** status in the console. New campaigns can't be booked on a product with these units (existing campaigns keep running), so revert the unit settings or remove the units from the creative set.

Changing the settings of a unit in a product or deleting the unit with the [Ad Unit API](https://docs.adrop.io/integrations/ad-units.md#impact-on-ad-products) also affects the product's creative sets.

### Targeting Policies

Each item in `targetings` is one targeting shown on the product. As in the console, use either audience targeting or context targeting in a product, not both.

| Field | Description |
| - | - |
| `targeting` | ID of an audience or context targeting in your project |
| `surchargeRate` | Premium rate in percent applied when this targeting is used (0 or more, no upper limit). For how it applies, see [Premium Rate Setting](https://docs.adrop.io/targeting/overview.md#premium-rate-setting). |
| `policies` | An object keyed by targeting option ID, with `{ "policy": "..." }` as values. Include only the options to show on the product. |

`policy` takes the same choices as the console.

| `policy` | Console | Description |
| - | - | - |
| `any` | Optional | Advertisers can select this option when booking a campaign. |
| `included` | Include | This option is always included in every campaign. |
| `excluded` | Exclude | This option is always excluded from every campaign. |

* Keys in `policies` must be top-level option IDs of that targeting. For an option group, use the group's ID, not the IDs of its sub-options. Other IDs return `400 AD_PRODUCT_TARGETING_INVALID`.
* A product can have up to 500 include (`included`) and exclude (`excluded`) policies. Optional (`any`) has no limit.
* If a context targeting has include or exclude policies, you can't add another context targeting with policies to the same product (`400 TARGETING_CONTEXT_EXCLUSIVE`).
* Adding the same targeting twice returns `400 TARGETING_DUPLICATED_IN_REQUEST`.
* Targeting IDs from other projects and IDs that don't exist return `400 AD_PRODUCT_TARGETING_INVALID`.

***

## List Products

Returns the project's products, newest first, one page at a time. Products scheduled for deletion are included with `deleteAt`.

### Request

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

Requires the `ad-product:read` scope.

### Query Parameters

| Parameter | Type | Required | Default | Description |
| - | - | :-: | - | - |
| `limit` | number | - | `20` | Number of products per page (1–120) |
| `next` | string | - | - | Cursor for the next page. Pass the `next` value from the previous response as is. Omit it for the first page. |

### Request Example

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

### Response Example

Returns `200` with `items` (the products) and `next` (the cursor for the next page). If there's no `next`, this is the last page.

```json theme={null}
{
  "items": [
    {
      "_id": "01JAZ3KB2C3D4E5F6G7H8J9K0M",
      "title": "Home Banner CPM",
      "private": false,
      "pricing": { "pricingType": "CPM", "price": 3000 },
      "discountRate": 0,
      "minBudget": 0,
      "frequency": 50,
      "metric": { "eImpressions": 100000, "eCTR": 1.5 },
      "options": {},
      "locale": { "country": "KR", "currency": "KRW", "timezone": "Asia/Seoul", "language": "ko" },
      "unitGroups": [{ "name": "Home Banner", "unitCount": 1, "fixRequiredCount": 0 }],
      "targetings": [{ "targeting": "01JAZ3K9Q8W5T2M4N6P7R8S9TV", "kind": "audience", "surchargeRate": 15 }],
      "createdAt": 1790820300000,
      "updatedAt": 1790820300000
    }
  ],
  "next": "01JAZ3KB2C3D4E5F6G7H8J9K0M"
}
```

List items differ from the [product object](#product-object) in two ways.

* `targetings` has no `policies`. If you need the policies, [get each product](#get-a-product).
* `unitGroups` has `unitCount` (number of units) and `fixRequiredCount` (number of units that need modification) instead of unit IDs.

The order is mostly newest first, but older products may be out of order. Don't rely on the order. Use `next` to read the following pages.

***

## Get a Product

Returns one product with its targeting policies.

### Request

```http theme={null}
GET /ad-products/{productId}
```

Requires the `ad-product:read` scope.

### Request Example

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

### Response

Returns `200` with a [product object](#product-object).

* `policies` contains only policies for the targeting's current top-level options. Policies for options that were deleted or moved into an option group aren't in the response.
* Products that use a context targeting with many options can have large responses. Get only the products you need.

### Errors

* `404 AD_PRODUCT_NOT_FOUND`: The product doesn't exist or belongs to another project.

***

## Update a Product

Changes only the fields you send.

### Request

```http theme={null}
PATCH /ad-products/{productId}
```

Requires the `ad-product:write` scope. The request body is the same as the [Request Body](#request-body).

### Query Parameters

| Parameter | Type | Required | Description |
| - | - | :-: | - |
| `ifUpdatedAt` | number | - | The `updatedAt` of the product you last read. If the product changed since then, the API returns `409 AD_PRODUCT_CONFLICT` and changes nothing. |

### How Updates Work

* Fields you don't send stay as they are. An empty body `{}` changes nothing.
* `unitGroups` and `targetings` are replaced as whole arrays. Creative sets and targetings you don't send are removed from the product.
* In the `pricing`, `metric`, `options`, and `locale` objects, only the keys you send change.
* If a `targetings` item omits `policies`, that targeting's policies stay as they are. If you send `policies`, they're replaced with the list you send, and policies for top-level options not in the list are removed.
* Creative sets are matched to existing creative sets with the same name, and only newly added units are checked. You can send units that already needed modification as they are.
* When you change the billing type to `INHOUSE`, the in-house values are set along with it.
* You can't clear the ad product name or remove all units from the product.

If the same product is also changed in the console, the last save wins. Updates that replace whole arrays, such as `unitGroups` and `targetings`, can overwrite changes made in the console in the meantime, so send `ifUpdatedAt` with them.

> [!TIP]
>
> If you take a get response, remove the response-only fields (`_id`, `createdAt`, `updatedAt`, `deleteAt`, `unitGroups[].fixRequired`, `targetings[].kind`, and the `locale` fields other than `currency`), and send the rest as is, nothing changes. To update safely, read the product, change only the values you need, and send it back.

### Request Example

```bash theme={null}
curl -X PATCH "https://lake.adrop.io/ad-products/01JAZ3KB2C3D4E5F6G7H8J9K0M?ifUpdatedAt=1790820300000" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "frequency": 80,
    "pricing": { "price": 3500 }
  }'
```

### Response

Returns `200` with the updated [product object](#product-object).

### Errors

* `404 AD_PRODUCT_NOT_FOUND`: The product doesn't exist or belongs to another project.
* `409 AD_PRODUCT_CONFLICT`: `ifUpdatedAt` differs from the product's `updatedAt`. Get the product again, then update it.
* `409 AD_PRODUCT_MUTATION_NOT_ACCEPTABLE`: The product is scheduled for deletion. [Restore it](#restore-a-product) first.

***

## Delete a Product

Schedules a product for deletion. Until the scheduled deletion time (`deleteAt`), you can [restore the product](#restore-a-product).

### Request

```http theme={null}
DELETE /ad-products/{productId}
```

Requires the `ad-product:write` scope.

### Request Example

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

### Response Example

Returns `200` with the product ID and the scheduled deletion time.

```json theme={null}
{ "_id": "01JAZ3KB2C3D4E5F6G7H8J9K0M", "deleteAt": 1791079500000 }
```

* If the latest end time among the product's campaigns is later than now, the product is deleted 3 days after that end time. Otherwise, it's deleted 3 days from now.
* Usually within a minute after the scheduled time passes, the product is deleted, and later requests for it return `404`.
* Products scheduled for deletion still appear in list and get responses with `deleteAt`, and they count toward the project's product limit. Deleting the product again recalculates the scheduled time.

### Errors

* `404 AD_PRODUCT_NOT_FOUND`: The product doesn't exist or belongs to another project.

***

## Restore a Product

Cancels a scheduled deletion and restores the product.

### Request

```http theme={null}
POST /ad-products/{productId}/restore
```

Requires the `ad-product:write` scope. Don't send a request body.

### Request Example

```bash theme={null}
curl -X POST "https://lake.adrop.io/ad-products/01JAZ3KB2C3D4E5F6G7H8J9K0M/restore" \
  -H "x-api-key: YOUR_API_KEY"
```

### Response

Returns `200` with the restored [product object](#product-object). Products that aren't scheduled for deletion also return `200`, and nothing changes.

### Errors

* `404 AD_PRODUCT_NOT_FOUND`: The product doesn't exist, belongs to another project, or was already deleted.

***

## Error Handling

### Error Response

Error responses include `statusCode`. Errors whose `errorCode` in the table below isn't `-` also include `errorCode`. Errors that point to a problem in the request also include `detail`. Handle errors by `errorCode`, or by `statusCode` when there's no `errorCode`.

```json theme={null}
{
  "statusCode": 400,
  "errorCode": "AD_PRODUCT_VALIDATION_FAILED",
  "timestamp": "2026-11-05T19:58:22+09:00",
  "detail": {
    "errors": [
      {
        "path": "pricing.price",
        "constraint": "isPositive",
        "message": "pricing.price must be greater than 0",
        "value": 0
      }
    ]
  }
}
```

In `detail.errors[]`, `path` is the location of the invalid field (such as `pricing.price`, `unitGroups[0].name`, or `targetings[0].policies.<option ID>`), and `value` is the value you sent. `detail.errors` holds up to 100 errors. After you fix them and resend, any remaining errors appear. Request format errors (`VALIDATION_FAILED`) also include the `message` and `error` fields.

### Error Codes

| Status | `errorCode` | Cause |
| - | - | - |
| `400` | `VALIDATION_FAILED` | The request format is invalid. You sent an unknown field or a response-only field, a value has the wrong type, format, or range, or the JSON is malformed. |
| `400` | `AD_PRODUCT_VALIDATION_FAILED` | A [product rule](#product-rules) was broken. `detail.errors` lists what's wrong. |
| `400` | `AD_UNIT_FIX_REQUIRED` | A unit you added doesn't match its creative set. `detail.mismatches[]` has `path` (location in the request), `unit` (unit ID), and `differences` (the items that differ). |
| `400` | `AD_PRODUCT_TARGETING_INVALID` | The targeting isn't in this project, or a policy key isn't a top-level option of the targeting. |
| `400` | `TARGETING_CONTEXT_EXCLUSIVE` | A context targeting with include or exclude policies was added with another context targeting that has policies. |
| `400` | `TARGETING_DUPLICATED_IN_REQUEST` | The same targeting was added twice. `detail.targetings` lists the duplicate IDs. |
| `400` | `AD_PRODUCT_TARGETING_POLICY_LIMIT_EXCEEDED` | The product has more than 500 include and exclude policies. |
| `401` | - | The API key is missing, invalid, or revoked. |
| `403` | - | The key doesn't have the required scope (`ad-product:read` or `ad-product:write`). |
| `404` | `AD_PRODUCT_NOT_FOUND` | The product doesn't exist or belongs to another project. |
| `408` | `REQUEST_BODY_TIMEOUT` | The request body wasn't fully sent within 30 seconds, or it was sent slower than 16 KB per second. |
| `409` | `AD_PRODUCT_CONFLICT` | `ifUpdatedAt` differs from the product's `updatedAt`. |
| `409` | `AD_PRODUCT_LIMIT_EXCEEDED` | The project already has 1,000 products, including products scheduled for deletion. |
| `409` | `AD_PRODUCT_MUTATION_NOT_ACCEPTABLE` | You tried to update a product scheduled for deletion. |
| `413` | - | The request body is larger than 8 MB, or a read request has a body. |
| `415` | `UNSUPPORTED_MEDIA_TYPE` | The request body isn't JSON or uses an unsupported character encoding. Use UTF-8. |
| `429` | `TOO_MANY_CONCURRENT_REQUESTS` | The concurrent request limit was exceeded. Wait for the number of seconds in the `Retry-After` header, then resend. |
| `502` | - | Internal server communication failed. |

### Retrying

* For `429`, wait for the time in the `Retry-After` header, then resend.
* If a write request (`POST`, `PATCH`, `DELETE`, or restore) gets `502` or the connection drops without a response, the request may have been applied. Get the product to check before resending. Create requests aren't idempotent, so resending one as is can create a duplicate product.
* When you resend an update with `ifUpdatedAt`, you can get `409 AD_PRODUCT_CONFLICT` if the earlier request was applied. Get the product again to check.

***

## Limits

| Item | Limit |
| - | - |
| Products per project | 1,000, including products scheduled for deletion. More return `409 AD_PRODUCT_LIMIT_EXCEEDED`. |
| Units per product | 1,000 (unique unit IDs across all creative sets) |
| Creative sets | 100 per product |
| Units per creative set | 300 |
| Targetings | 200 per product |
| Include and exclude policies | 500 per product |
| Policy keys | 100,000 per request, across all targetings |
| Ad product name | 200 characters |
| Creative set name | 100 characters |
| Creative guide link | 2,048 characters |
| Request body | 8 MB |
| Concurrent requests | 4 per project. 2 per project for requests with bodies larger than 100 KB. |
| Request body upload | Within 30 seconds, at 16 KB per second or faster |
| Response download | If you don't receive the whole response within 30 seconds, the server closes the connection. |


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