Documentation / Platform glossary / Idempotency Key
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.
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.
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.
QueryTek treats idempotent writes as a design goal for partner and customer automation. In QueryTek Review™, the integrator API accepts an optional idempotency key on document intake submissions: a retry with the same key and the same request returns the original result, and the same key sent with a different request is rejected. Exact header names, retention windows, and error codes belong to each product's developer documentation.
