Idempotency

A network can fail after DialerBee has done the work but before you get the answer. The Idempotency-Key header makes a retry safe: the same key always gets the same result, and the write happens at most once.

When to send it

Required on every POST and DELETE that changes data. Without it the request is refused with 400 idempotency_key_required.
Optional on PATCH. When sent, it behaves exactly the same.
Not used on GET.

Use a new, unique value for each logical operation, for example a UUID, or your own record id plus an attempt-independent suffix. Up to 255 printable characters.

What DialerBee does with it

Situation	Answer
First request with this key	Processed normally; the answer is stored.
Same key, same request, after it finished	The stored answer, with `Idempotency-Replayed: true`. A webhook signing secret is never kept in the stored answer, so it is `null` in a replayed answer.
Same key, same request, while the first one still runs	409 `conflict` with `Retry-After`. Retry after it: you then get the stored answer.
Same key, a different request	409 `idempotency_conflict`.
DialerBee could not confirm whether the write happened	409 `outcome_unknown`, for this key, until DialerBee has reconciled it.

"The same request" means the same method, the same operation, the same path and query parameters and the same JSON body.

Keys are scoped to your API client: two integrations of one account never see each other's answers, and a key rotation does not change anything.
Keys are kept for 24 hours. After that the key can be used again.

outcome_unknown: never retry with a new key

outcome_unknown means the platform accepted the request but could not confirm the result. The lead may have been imported; the campaign may have resumed. Retrying with a new key could do it twice.

Do not retry with a new key.
Retry later with the same key: once DialerBee has reconciled it, you get the real answer.
Or read the resource to see what happened, or contact support with the request_id.

Retrying correctly

Store the idempotency key with your own record before the first attempt, so a crash of your own process can retry with the same key.
Retry only on network errors, 409 conflict, 429, 502, 503 and 504; wait Retry-After when it is sent, otherwise back off exponentially with jitter.
Never retry outcome_unknown, idempotency_conflict, daily_cap_reached or tier_not_enabled with a new key.

The Python SDK follows these rules for you.