Retries and idempotency

This page says what DataFlair does when your server is slow, returns an error, or receives the same request twice. It separates what the platform does today from what the contract describes for calls that are not live yet.

Timeouts

DataFlair waits up to 10 seconds to connect to your server and up to 30 seconds in total for one call. These are the platform's configured defaults. They apply to every call to your server.

Retries today

Today DataFlair calls two endpoints: GET /health and GET /inventory, when an operator connects or re-verifies.

Neither call is retried. If it fails, DataFlair records the failure, and the operator presses Re-verify in DataFlair after fixing the cause.

Other facts about how DataFlair makes these calls:

• DataFlair does not follow redirects. A 3xx answer is not followed.
• DataFlair resolves your host on every call. The host must resolve to public addresses only.
• Only GET /health decides the connection state. A failed GET /inventory leaves Inventory read as Not verified and does not fail the connection.

Calls that are not live yet

DataFlair does not call POST /forecast, POST /orders or POST /reports yet. No retry behaviour exists for them in the platform. The contract asks you to expect the reactions below when they go live. Treat the table as the contract and not as current behaviour.

Your answer	Contract: what DataFlair does
429 with Retry-After	Backs off for that many seconds, then retries.
5xx, or no answer	Retries with backoff. A persistent failure shows as "your platform is unreachable".
409	Logs it. Does not retry it blindly.
404	Skips that item and reports it.
422	Shows your message to the operator. Does not retry.
501 on POST /forecast	Treats the slot as "no forecast available".

The contract also says DataFlair may send POST /orders again for the same campaign. It happens when a publisher clicks "re-push", and when a later creative approval re-traffics. It can also happen on an automatic retry.

Idempotency for POST /orders

A booking can arrive more than once. Your API must make a repeat safe. There are two cases, and they use different keys.

Case	What arrives	What you do
A literal retry	The same idempotency_key and the same body.	Return the same result with 200. Create nothing new.
A conflict	The same idempotency_key and a different body.	Reject it with 409. Do not guess which body is right.
An update	A new idempotency_key and the same order.external_ref and line_items[].external_ref.	Match on external_ref. Update only what changed. Return the same order_id and line_item_id values with 200.

Read calls (/health, /inventory, /forecast, /reports) are idempotent by nature. DataFlair can repeat them freely.

The full rules and an example are on POST /orders and in Conventions.

What to build now

• Answer every call inside 30 seconds, and connect inside 10 seconds. A slow answer counts as a failure.
• Return 429 with Retry-After when you need DataFlair to slow down.
• Make POST /orders idempotent as described above, even though DataFlair does not call it yet.