Idempotency

​

How it works

curl -X POST https://your-kordless-instance.com/v1/quotes \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "businessId": "9d2c7f1e-…",
    "bookId": "b3a1…",
    "offeringId": "ceramic-pro",
    "factors": { "vehicle_size": "large" },
    "idempotencyKey": "order-7392-attempt-1"
  }'

• Same key, same payload → the original Quote Intent and Receipt are returned (a replay). No new Quote, no duplicated usage event.
• Same key, different payload → 409 with code: "idempotency_conflict". The server refuses to guess which request you meant.
• No key → the server generates one (auto_<uuid>). The Quote is still safe from accidental double-submits inside the same request lifecycle, but you cannot replay it yourself — always send your own key for any request you might retry.

​

Key rules

​

The retry pattern

1. Generate one key per logical submission (for example, per checkout attempt).
2. Send the request. On a timeout or 5xx, retry with the same key and the same payload.
3. On 2xx, store the Quote ID. Any later retry with the same key returns that same Quote.
4. On 409 idempotency_conflict, the payload changed under a reused key — treat it as a bug in your key discipline, not as a transient error.

​

Edited submissions

let pendingKey: string | null = null;

function onInputEdited() {
  pendingKey = null; // next submit must use a fresh key
}

async function submit(payload: QuotePayload) {
  pendingKey ??= `quote_${crypto.randomUUID()}`;
  return createQuote({ ...payload, idempotencyKey: pendingKey });
}

​

What idempotency does not do

• It does not deduplicate across different keys. Two different keys with identical payloads create two Quotes.
• It does not make reads consistent — GET replays nothing; it reads current state (Receipts are immutable, so Quote reads are stable anyway).
• It does not replace error handling. A 422 will fail identically on every replay.