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.

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

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.