Idempotency
Use the Idempotency-Key header to retry a POST safely without creating duplicates.
When a POST times out or the connection drops, you cannot tell whether the request never arrived or succeeded and the answer was lost. Retrying blindly can create the same client, ticket or deal twice.
Send an Idempotency-Key header and Dashly guarantees the request runs at most once: a retry with the same key gets the first answer back instead of running again.
curl -X POST https://api.usedashly.com/v1/clients \
-H "Authorization: Bearer $DASHLY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 7d3f0a52-crm-import-row-1842" \
-d '{ "name": "Lumen Bakery", "status": "prospect" }'Rules
POSTonly. The header applies to creations and to actions. It is ignored onGET(already safe to repeat) and onPATCHandDELETE, which name the record they change.- Optional. A
POSTwithout the header behaves normally. - Format. 8 to 255 characters from
A-Z a-z 0-9 _ . : -. Anything else is refused with400 invalid_request. A UUID is a good choice. - Scoped to the key. The same value used with two different API keys counts as two different keys.
- One key, one request. A key is tied to the method, the path and the exact body of its first request.
- Kept for 7 days. After that, the same key is treated as new.
What you get back
| Situation | Answer |
|---|---|
| First request with this key | The request runs normally. |
| Same key, same request, first one finished | The stored answer of the first request, same status and body, with the header Idempotent-Replay: true. Nothing runs again, and no quota is spent. |
| Same key, same request, first one still running | 409 conflict, details.reason: "idempotency_key_in_flight". Retry a little later. |
| Same key, different method, path or body | 409 conflict, details.reason: "idempotency_key_conflict". Use a new key for a new request. |
{
"error": {
"code": "conflict",
"message": "This \"Idempotency-Key\" was already used for a different request.",
"details": { "reason": "idempotency_key_conflict" },
"request_id": "req_…"
}
}When the first request fails with an error, its key is released, so a corrected or repeated request with the same key runs again.
Choosing keys
Generate one key per intended operation, and reuse it only for retries of that operation:
- a UUID created when the job is queued and stored with it, or
- a value derived from your own data, such as
crm-sync:contact:4821, when each source record must create exactly one Dashly record.
Do not reuse a key for a new request, even an identical one you really want to run twice: the second call returns the first result.