zero gravitySOLUTIONS
← All insightsSAAS ENGINEERING / REQUEST CONTRACT GUIDE

Tenant-aware API idempotency

QUICK ANSWER

Scope idempotency by authenticated tenant and business operation, then bind the key to a canonical request fingerprint. Claim the operation atomically, replay only authorized results, and define retention and in-progress behavior explicitly. A key alone is not a complete idempotency contract.

Inside this article 5 sections

An idempotency key says that two requests represent the same intended operation. In a multi-tenant API, that identity must include the authenticated account context. Otherwise, two customers who happen to submit the same key can collide, and careless response replay can become an information disclosure.

Use an illustrative purchase-order API. A customer submits an order, the connection drops, and the client repeats the request. The desired result is one order plus an authoritative way to discover it. That requires a durable operation record, a concurrency rule, and a clear relationship between the key and the request contents.

Define the identity tuple before the header

A practical uniqueness scope is authenticated tenant, operation kind, and client-supplied key. Depending on the product, a tenant may contain separate billing accounts or workspaces that require another scope component. Choose the boundary that matches business ownership, then document it. Never derive the authoritative tenant solely from an untrusted request body.

Operation kind prevents a key used to create an order from accidentally colliding with a key used to cancel one. Include contract version where a version change alters the meaning of the operation. Keep keys opaque and avoid embedding email addresses or other sensitive data that may be copied into logs.

ILLUSTRATIVE PURCHASE-ORDER IDENTITY
Uniqueness
Authenticated tenant + create-order operation + opaque client key.
Request binding
A fingerprint of canonical, business-relevant request fields.
Durable state
Claimed, processing, succeeded, rejected, or awaiting reconciliation.
Replay result
Authorized access to the stored operation outcome and canonical order reference.
The key identifies intent within a scope. The fingerprint detects a different request incorrectly presented as the same intent.

Compare meaning rather than raw JSON formatting

Two JSON bodies can mean the same thing while ordering fields differently. Normalize the relevant inputs before computing the fingerprint: selected defaults, numeric representation, and any fields whose ordering is semantically irrelevant. Do not reorder a list when order is meaningful to the business. Version this normalization if later changes would alter equivalence.

Exclude transient transport details such as trace identifiers. Include fields that change the effect, including currency, item quantities, and the target account where appropriate. If an existing key arrives with a different fingerprint, return a clear conflict rather than silently replaying the old result or performing the new action.

Validation order also belongs in the contract. Authenticate and authorize access before revealing stored results. Decide whether a request rejected before execution consumes its key, and distinguish that from a business rejection recorded after an operation begins. Clients need to know whether corrected input should reuse the key or create a new intended operation.

Make simultaneous requests compete atomically

A read-then-insert check is vulnerable to concurrency: two requests can both observe that no key exists and both execute. Enforce uniqueness in durable storage on the full scope tuple, with all required identity columns non-null. One request claims the operation; another observes the existing claim and follows the published in-progress behavior.

For a database-only order creation, the operation record and business mutation may be committed in one transaction. If the process stops before commit, neither becomes visible. If it stops after commit but before responding, a repeated request can discover the completed operation. Keep the stored result sufficient for replay without depending on ephemeral application memory.

External effects require another design step. A database transaction cannot atomically commit a remote provider action. Persist intent, use the provider's own idempotency contract where available, and represent uncertain outcomes explicitly. Expiring a local claim does not prove that an old worker has stopped or that the remote effect never happened.

This minimal SQL schema illustrates the durable uniqueness boundary. All identity components are non-null; the authenticated tenant and normalized request hash are supplied by server code. It deliberately leaves response storage and operation execution to the surrounding transaction protocol.

CREATE TABLE request_claims (
    tenant_id TEXT NOT NULL,
    operation_kind TEXT NOT NULL,
    idempotency_key TEXT NOT NULL,
    request_hash TEXT NOT NULL,
    state TEXT NOT NULL CHECK (state IN ('pending', 'completed', 'rejected')),
    PRIMARY KEY (tenant_id, operation_kind, idempotency_key)
);

On a uniqueness conflict, load the existing claim and compare its request hash before returning or resuming anything. Two tenants may use the same client key without colliding. A failed insert alone does not tell you that the original operation completed, and deleting a pending claim can reopen the same business intent. Test the full protocol with simultaneous requests against the production database engine.

Publish in-progress and retention behavior

Choose whether a duplicate in-progress request waits briefly, receives a conflict-style response, or gets an operation resource to poll. Avoid holding unlimited HTTP connections while the original request performs long-running work. A durable operation endpoint is often clearer for imports, provisioning, and other asynchronous capabilities.

Recheck authorization before replaying sensitive output. A user may have lost account access since submitting the original request. Store only the response information needed for the contract, apply appropriate access controls, and define whether replay returns the original representation or a canonical resource reference whose current state can be fetched separately.

State the retention window in client-facing documentation. Removing an operation key can permit an old retry to create a new effect. Where the business identity must remain unique indefinitely, enforce that separately from the shorter-lived response cache. An order's external reference can be a durable business constraint even after the detailed replay response expires.

Test the races that the contract promises to handle

Send the same key concurrently with identical bodies and verify one intended order. Repeat with different bodies and expect a conflict. Use the same key in two tenants and verify isolated results. Interrupt after commit, revoke the caller's access, and test retry behavior around retention expiry. Count business effects, not merely successful HTTP responses.

The optimistic UI guide explains how clients represent these outcomes, and reliable background jobs carries identity into workers. API implementation should join these contracts so every layer agrees on what “the same operation” means.

FROM INSIGHT TO ACTIONCustom software development

Give API retries a reliable contract.

We can implement tenant-scoped idempotency, concurrent-request handling, and result reconciliation across your API and workers.

Explore software developmentDiscuss your build

Start with your goals.
We’ll work through the next step together.