Conventions / Idempotency

Idempotency

Every POST accepts an optional Idempotency-Key header. It lets you safely retry a request after a network blip without creating a duplicate.

Send an Idempotency-Key on any write you might retry, such as creating a site or publishing a flow. Generate one UUID per logical operation, not per HTTP call.

How it works

Keys are scoped per API key, so your key and another key can use the same value without colliding.

Send the same key with the same body within 24 hours and you get the original response back. The retry is a no-op.

Send the same key with a different body and the API returns 400 with idempotency_key_in_use. Pick a new key.

Server errors are never cached, so retrying after a 502 or 5xx re-runs the request.

Example

Pass the key as a header alongside your request body.

Terminal

curl https://app.converly.io/api/v1/sites \
  -H "Authorization: Bearer sk_live_…" \
  -H "Idempotency-Key: 8f3c1a90-7b2e-4c6f-9a1d-2e5b8c0f4d21" \
  -d '{
    "name": "Northwind",
    "domain": "northwind.com"
  }'