## Error Handling

| Message | Reason(s) |
| --- | --- |
| `Out of n% placements on the request, none were valid` | - The siteId has been deleted<br>- The siteId is not active<br>- No siteId on the request |
| `Keywords must be an array or string` | Keywords are not a string or an array of strings |
| `invalid JSON` | JSON is not valid |
| `Request received with no placements defined` | The `placements` object or the request body is missing |
| `No sites found` | Invalid SiteId provided in the request |
| `Count must be an integer in the interval [1, 20]` | `placements.count` in the request is not between `1` and `20` |
| `Event multiplier must be an integer in the interval [1, 100000000]` | `placements.eventMultiplier` in the request is not between `1` and `100000000` |

### Request Structure

- **networkId** (int32) - required: Your account (network) ID
- **placements** (array of objects) - required: Every request must contain one or more placements. Each placement represents a "slot" in which an ad may be served.
  - **user** (object) - Object containing the UserKey used for [UserDB targeting](https://dev.adzerk.com/docs/userdb-1).
  - **keywords** (array of strings) - Keywords for [Keyword Targeting](https://dev.adzerk.com/docs/keyword-targeting). Such as `"keywords": ["foo", "bar", "baz"]`
  - **url** (string) - The current page URL
  - **referrer** (string) - The referrer URL
  - **ip** (string) - The IP address. Required for [Geo-Targeting](https://dev.adzerk.com/docs/geo-location)
  - **includePricingData** (boolean) - Defaults to false. If true, return pricing data for the decision in the response.
  - **includeRelevancyData** (boolean) - Defaults to false.
  - **notrack** (boolean) - Defaults to false.
  - **enableBotFiltering** (boolean) - Defaults to false.
  - **enableUserDBIP** (boolean) - If true, override the IP address of the request with the IP address supplied on the UserKey.
  - **consent** (object) - Object that sets the data consent preferences.
  - **deviceID** (string) - RTB requests only - sets an Identifier for Advertisers (IFA or IDFA)
  - **parallel** (boolean) - Defaults to false.
  - **intendedLatitude** (float) - (BETA) Latitude to use for [Distance Targeting](https://dev.kevel.co/docs/distance-targeting).
  - **intendedLongitude** (float) - (BETA) Longitude to use for [Distance Targeting](https://dev.kevel.co/docs/distance-targeting).
  - **radius** (float) - (BETA) Radius of the user if using user-specified radius with [Distance Targeting](https://dev.kevel.co/docs/distance-targeting).
  - **time** (integer) - Expects a Unix epoch timestamp in the future.
  - **searchTerm** (string) - See [Search Term Targeting](https://dev.kevel.com/docs/search-term-targeting).
  - **block** (object) - Prevents specific advertisers, campaigns, creatives, or flights from being served in the response.

### Example Request

```shell
curl -H 'Content-Type:application/json' \
  -X POST \
  -d '{"user":{"key":"abc"}, "placements":[{"divName":"div0", "networkId":23, "siteId":667480, "adTypes":[5]}]}' \
  https://e-23.adzerk.net/api/v2
```

### Example Response

```json
{
  "user": {
    "key": "abc"
  },
  "decisions": {
    "div0": {
      "adId": 1111,
      "creativeId": 2222,
      "flightId": 3333,
      "campaignId": 4444,
      "advertiserId": 5555,
      "priorityId": 6666,
      "clickUrl": "https://e-23.adzerk.net/r?...",
      "contents": [{
        "type": "html",
        "body": "<a href='...'><img src='https://static.adzerk.net/Advertisers/cat.jpg' title='ZOMG A CAT' width='350' height='350'></a>",
        "template": "image",
        "data": {
          "imageUrl": "https://static.adzerk.net/cat.jpg",
          "title": "ZOMG A CAT",
          "width": 350,
          "height": 350,
          "customData": {
            "headline": "Test Headline",
            "cta": "Download Here"
          }
        }
      }],
      "impressionUrl": "https://e-23.adzerk.net/i.gif?...",
      "events": [
        {"id": 12, "url": "https://e-23.adzerk.net/e.gif?..."},
        {"id": 13, "url": "https://e-23.adzerk.net/e.gif?..."},
        {"id": 14, "url": "https://e-23.adzerk.net/e.gif?..."}
      ],
      "pricing": {
        "price": 5,
        "clearPrice": 2.01,
        "revenue": 0.002,
        "rateType": 2,
        "eCPM": 5
      }
    }
  },
  "candidateRetrieval": {
    "div0": {
      "candidatesFoundCount": 1
    }
  }
}
```