Idempotency

A network failure after you send a POST leaves you not knowing whether it happened. An Idempotency-Key makes the retry safe.

How it works

Generate a unique key per logical operation (a UUID is ideal) and send it as the Idempotency-Key header on the POST.
The first response — success or a 4xx — is stored against that key for 24 hours.
A retry with the same key and the same body returns the stored response unchanged, with Idempotent-Replayed: true, and does nothing again.
The same key with a different body answers 409 conflict.

Keys are 1–100 characters of letters, digits and - _ : ., scoped to the API key that sent them. Only POST uses them; PATCH and DELETE are already safe to repeat. Server errors (5xx) are not stored, so they can be retried with the same key.

Request (sent twice)

curl -X POST https://api.digitalagency.tools/v1/contacts \
  -H "Authorization: Bearer $DA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c1e8a52-1d0b-4f39-9e61-0c2d4b5a8f13" \
  -d '{"name":"Niamh Kelly"}'

Second response · 201

HTTP/2 201
Idempotent-Replayed: true

{ "data": { "id": 482, "name": "Niamh Kelly", … }, "meta": { … } }

Same key, different body · 409

{
  "error": {
    "type": "conflict",
    "message": "This Idempotency-Key was already used with a different request."
  },
  "meta": { "request_id": "req_…" }
}