Idempotency

A request that times out is not a request that failed. Send an idempotency key and retrying is safe.

How to use it

curl https://api.kleos.click/v1/customers \
  -H "Authorization: Bearer kls_live_..." \
  -H "Idempotency-Key: signup-8842" \
  -H "Content-Type: application/json" \
  -d '{"name":"Vandeputte Plumbing","country":"BE"}'

Any string you choose, unique to the operation you are performing. A UUID per signup attempt works; so does your own record id. Kleos remembers it for 24 hours and replays the original response, with the original status code, to any repeat of the same request.

Same key, different body

That is a 409 idempotency_key_reused, not a replay. Returning the first response would be a lie about what was created — you asked for one thing, we would be telling you about another. Use a new key when the request changes.

Which endpoints honour it

Every endpoint that creates something or spends something. Reads do not need it. Sending the header on a read is harmless and ignored.

The second safety net

Customer creation is also protected by external_ref: creating the same reference twice returns the existing customer with 200 rather than 201. So a retry survives even if the idempotency header was lost along the way. Check the status code if you need to know which of the two happened.