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_CONFLICTas a transient server error