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