Idempotency

​

The header

Idempotency-Key: <arbitrary-string>

• Client-generated. UUIDs are recommended; any unique string up to 255 characters works.
• Scoped per (organizationUuid, key). Keys don’t collide across customers.
• Stored with the response for 24 hours.

​

Behavior matrix

​

Example — safe create-then-retry

async function createBuyer() {
  const idempotencyKey = crypto.randomUUID();
  const body = {
    kycMode: 'MARKETPLACE_LED',
    vatNumber: 'DE123456789',
    companyName: 'AutoHandel Mustermann GmbH',
    address: { ... },
  };

  for (let attempt = 0; attempt < 3; attempt++) {
    const r = await fetch(url, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${token}`,
        'Idempotency-Key': idempotencyKey,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(body),
    });

    if (r.ok) return r.json();
    if (r.status >= 500 || r.status === 408) {
      // Transient — retry with the SAME key and SAME body.
      await sleep(Math.pow(2, attempt) * 1000);
      continue;
    }
    throw new ApiError(r.status, await r.json());
  }
}

• Generate one key per logical operation. Not per HTTP attempt.
• Persist the key if your retry might span a process restart — reuse the same key after restart.
• Never reuse a key for different data — even small changes trigger 422. Fresh data = fresh key.

​

Natural-key upsert (second layer)

• Same body → 200 OK with existing resource. Idempotent regardless of the Idempotency-Key.
• Different body → 409 Conflict with current resource. Use PATCH for explicit updates.

​

Why two layers

• Header handles short-window network-retry dedup with exact-response replay.
• Natural key handles cross-channel dedup — the same buyer created via API and then “discovered” via web app still converges to one record.

​

What happens when I send Idempotency-Key with a GET request?

​

Next