Idempotency key
In Short
An idempotency key is a client-supplied token that lets an API recognize a retried write as the same logical operation. When networks time out or clients retry automatically, the server can return the original outcome instead of creating a duplicate record — which is essential for payments, provisioning, and other side-effecting calls.
Definition
HTTP POST and PATCH are not inherently safe to repeat. An idempotency key — usually sent in a dedicated header — gives the server a stable handle for deduplication within a time window. The first request with a given key performs the work and stores the result; subsequent requests with the same key replay that stored result without re-executing side effects.
Good key design is the caller's responsibility. Keys should be unique per intended operation (often a UUID), scoped to the authenticated principal or tenant, and retained long enough to cover realistic retry horizons. Reusing a key for a different payload is a logic bug: the server should reject the mismatch rather than silently applying the wrong semantics.
Idempotency complements — but does not replace — correlation identifiers. A correlation ID traces a request through logs; an idempotency key controls whether the business operation runs once.
Why It Matters
Integrations fail in production because retries are inevitable. Without idempotency, a transient timeout can produce duplicate enrollments, double charges, or repeated webhook deliveries — defects that are hard to unwind and expensive to explain during diligence.
How QueryTek Uses It
QueryTek's integration surfaces treat idempotent writes as a baseline expectation for partner and customer automation. Public documentation describes the industry pattern; product-specific header names, retention windows, and error codes are documented in the Review, Tapestry, and EBM glossary scopes where those APIs are exposed.