---
url: https://docs.dataflair.ai/marketplace/ad-server-api/troubleshooting.md
description: >-
  Common failures when you connect your ad server to DataFlair, listed by what
  you see, with the cause and the fix.
---

# Troubleshooting

Find the symptom, read the cause, apply the fix. Every message below is what DataFlair shows on the **Custom ad server** card in **Settings**, then **Ad server**.

## The form will not save

| What you see | Cause | Fix |
| --- | --- | --- |
| The base URL is rejected because it is not `https`. | DataFlair accepts `https://` URLs only, so the key is not sent in clear text. | Use an `https://` base URL. |
| "This URL cannot be used." The message says the URL must resolve to a public address. | The host is `localhost`, a private or internal address, a name ending in `.local`, `.internal`, `.lan` or `.localhost`, or a numeric host. | Use a public hostname. Expose your sandbox on a public URL if you need to test. |
| "This URL cannot include a # fragment." | DataFlair adds `/health` and `/inventory` after the URL, so anything after `#` would swallow them. | Remove the `#` and everything after it. |
| The API key is rejected because it has characters that cannot be sent in an HTTP request. | The key has a line break or another control character. | Paste the key again with no trailing newline. |
| The base URL is longer than 255 characters. | The base URL has a limit of 255 characters. | Use a shorter URL. |
| "Only workspace owners and admins can connect the ad server." | Your role cannot connect. | Ask an owner or an admin. |
| "Another connection change for this organization is in progress. Please try again shortly." | Two changes to the same organization ran at once. | Wait a moment and try again. |

## The connection fails

| What you see | State | Cause | Fix |
| --- | --- | --- | --- |
| "DataFlair could not authenticate. Check your API key, then reconnect." | `auth_error` | `GET /health` answered `401`. | Check the key on your ad server. Reconnect. |
| "Your API key doesn't have the required scope. Update its permissions on your ad server, then reconnect." | `forbidden` | `GET /health` answered `403`. | Give the key read, create-draft and report scope. Reconnect. |
| "Your ad server could not be reached. Check the base URL, then reconnect." | `unreachable` | No answer within 10 seconds to connect or 30 seconds in total, a DNS failure, or a `4xx` or `5xx` other than `401` and `403`. | Check the base URL and your server. Look at your server's logs for the `GET /health` request. |
| "Your ad server responded, but not in the documented /health shape. Check your /health endpoint, then reconnect." | `invalid_response` | The body of `GET /health` is missing a field or has a bad value. | Check every field. See [GET /health](/marketplace/ad-server-api/operations/health#fields). |

The four fields DataFlair checks most often are `account_id` (not empty), `timezone` (a real IANA name, not `UTC+2`), `currency` (three uppercase letters, not `EURO`), and the `capabilities` flags (booleans, with `reporting` and `draft_booking` set to `true`).

### My server redirects

DataFlair does not follow redirects. A redirect from `http` to `https`, or from `/health` to `/health/`, is not followed. Enter the final URL as the base URL, and serve `/health` without a redirect.

## The connection works, but a capability shows "Not verified"

| Capability | Why | What to do |
| --- | --- | --- |
| **Inventory read** | The card confirms it when `GET /inventory?limit=1` returns `200` with a `data` array. A failed call here does not fail the connection. | Check that `GET /inventory` returns a `data` array. Click **Re-verify**. |
| **Forecast**, **Reporting**, **Draft booking** | DataFlair does not call these endpoints yet. The card says "not built yet". | Nothing. This is the expected state today. See the [overview](/marketplace/ad-server-api/overview). |

## The card says "Re-verify needed"

The last verification failed. The card shows the reason from the tables above. Fix the cause and click **Reconnect & verify**. If a reconnect fails, DataFlair keeps your last working base URL and key.

## Still stuck

Send DataFlair support the exact text on the card and the time of the attempt. Do not send the key.