Idempotency

Use this page to make retried write operations safe and predictable.

Who This Is For

developers implementing retries for runtime or management writes
backend teams building resilient automation
operators debugging duplicate or conflicting writes

When To Use This

Read this before adding automatic retries to mutation endpoints.

Only send Idempotency-Key on operations that accept it. Reusing the same key with a different request body is a conflict, not a retry.

How It Works

LicenseKit uses the Idempotency-Key header to make specific writes replay-safe.

Common idempotent write flows in the current contract include:

runtime activation
runtime metered consume
runtime deactivation
floating checkout
floating checkin
license renewal
license transfer

Behavior to rely on:

retry the same logical operation with the same body and key
do not reuse the same key for a different logical operation
a mismatched replay returns IDEMPOTENCY_CONFLICT

Example

bash

curl -X POST https://api.licensekit.dev/api/v1/license/consume \
  -H "Authorization: License $LICENSE_KEY" \
  -H "Idempotency-Key: consume-evt-123" \
  -H "Content-Type: application/json" \
  -d '{
    "fingerprint": "host-123",
    "feature_code": "api_calls",
    "amount": 1,
    "event_id": "evt_123"
  }'

If the client times out after sending that request, retry with the same header and the same body.

Common Mistakes

generating a new idempotency key for a retry of the same logical action
reusing a key across different request bodies
assuming every write route supports idempotency automatically
treating IDEMPOTENCY_CONFLICT as a transient server error

Idempotency ​

Who This Is For ​

When To Use This ​

How It Works ​

Example ​

Common Mistakes ​

Related Pages ​