---
url: https://docs.dataflair.ai/marketplace/ad-server-api/errors.md
description: >-
  Every error code and HTTP status in the Ad Server API, what causes it, what
  DataFlair does, and how to fix it.
---

# Errors

Use this page when something breaks. There are two tables. The first is what **your API** returns and how DataFlair reacts. The second is what the **DataFlair connection card** shows when a connection fails.

## What your API returns

Every non-2xx response has a JSON body. `code` is a stable, machine-readable slug that you choose. `message` is text for a person. See the [error model](/marketplace/ad-server-api/conventions#error-model).

::: code-group

```json \[supplemental/forecast-unknown-slot/expected-response.json]
{
  "code": "inventory_not_found",
  "message": "No ad slot exists for inventory_id 'slot_x'.",
  "details": {
    "inventory_id": "slot_x"
  }
}

```

:::

| HTTP status | Example `code` | What caused it | What DataFlair does | How to fix it |
| --- | --- | --- | --- | --- |
| `400` | `bad_request` | Invalid JSON, a wrong field type or a missing field. | Treats it as a bug, logs it and shows it. On `GET /health`, the connection shows `unreachable`. | Check the request against the endpoint's field table. |
| `401` | `unauthorized` | Missing, invalid or expired key. | Marks the connection as `error`, with the state `auth_error`. | Check the key. Issue a new one if you must, then reconnect in DataFlair. |
| `403` | `forbidden` | The key authenticated but lacks a scope. | Marks the connection as `error`, with the state `forbidden`. | Give the key read, create-draft and report scope. |
| `404` | `inventory_not_found` | An unknown `inventory_id`, `order_id` or `line_item_id`. | Skips that item and reports it. It does not force the item onto a booking. | Return `404` only for an id that does not exist on your side. |
| `409` | `idempotency_conflict` | The same `idempotency_key` arrived with a different body. | Logs it. Does not retry it blindly. | Reject the call. Do not apply the new body. See [Retries and idempotency](/marketplace/ad-server-api/retries-and-idempotency). |
| `422` | `invalid_date_range` | The shape is valid and a value is not: a bad date range, or a size that does not fit the slot. | Shows your `message` so the operator can fix the booking. | Return a clear `message` that names the field and the problem. |
| `429` | `rate_limited` | DataFlair went over your budget. | Backs off per `Retry-After` and retries. | Send `Retry-After` in seconds. Publish your budget in your handoff notes. |
| `501` | `forecast_unsupported` | One slot cannot be forecast. | Shows "no forecast available" for that slot. It does not block the booking. | See [If you cannot forecast](/marketplace/ad-server-api/operations/forecast#if-you-cannot-forecast). |
| `5xx` | `server_error` | Your server failed. | Retries with backoff. A persistent `5xx` shows as "your platform is unreachable". | Check your server's logs. |

The `code` values other than `inventory_not_found` and `forecast_unsupported` are examples. The contract does not fix them. Pick stable slugs, and keep them.

## What the DataFlair connection card shows

When you connect or re-verify, DataFlair calls `GET /health`. If it fails, the card shows one of four states. The state comes from the HTTP status and the body.

| State | HTTP status | What caused it | How to fix it |
| --- | --- | --- | --- |
| `auth_error` | `401` | The key is wrong, missing or expired. | Check the key on your ad server. Enter it again and click **Reconnect & verify**. |
| `forbidden` | `403` | The key has no scope for what DataFlair calls. | Widen the key's scope on your ad server. Then click **Reconnect & verify**. |
| `unreachable` | `400`, `404`, `429`, any other `4xx`, any `5xx`, or no answer | Your server was down, too slow, or answered with an error. A wrong base URL also lands here. A host that does not resolve to a public address is refused. | Check the base URL. Check your logs. DataFlair waits 10 seconds to connect and 30 seconds in total. |
| `invalid_response` | `200` | The body does not match the `/health` fields. | Fix the body. See [GET /health](/marketplace/ad-server-api/operations/health#fields). |

DataFlair also stores the `message` from your error body as the last error, with credentials redacted. Do not put secrets in `message`.

DataFlair does not follow redirects. Serve every endpoint at the exact base URL you entered.

For symptoms and step-by-step fixes, see [Troubleshooting](/marketplace/ad-server-api/troubleshooting).