Idempotency – API docs

curl -X POST 'https://www.debt-flow.io/api/v1/contacts' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 4f0c2a7e-crm-sync-1832' \
  -d '{"name":"Muster GmbH"}'

Case	Response
First request with a new key	executed normally; the response is stored for 24 hours
Same key, same request	stored response with the header `Idempotent-Replayed: true`
Same key, different request	`422 idempotency_conflict`
First request still running	`409 idempotency_in_progress` – wait briefly, then retry
First request ended with 5xx	the key is released; the retry is executed again

Key: 8 to 255 characters from A–Z a–z 0–9 _ - : ., for example a UUID.
The key applies per API key or OAuth connection; different integrations do not interfere with each other.
“Same request” means: same method, same path and same body.
Applies to POST endpoints except file uploads; the API reference lists the header for every supported endpoint. GET, PATCH and DELETE can be retried anyway.

One key per operation

Generate the key when the business operation is created (for example “create invoice for order 1832”) and store it with the operation. A new key for every attempt would defeat the protection.