Skip to content
AITroveRead. Build. Understand.
Reading list
Make this comfortable

Idempotent Write Requests and Lost Responses

Last updated: 5 Oct 20266 min read
tutorial
IntermediateBy AITrove Editorial

A client timeout does not prove that a write failed. The server may have committed the record and lost only the response. For an operation that must happen once per user intent, accept an idempotency key scoped to the caller and operation. Store the key, request fingerprint, and first result atomically with the effect. A retry with the same key and same input returns that result; the same key with different input is a conflict. Retain keys for a documented window and decide what happens when that window expires. Idempotency is a server contract, not a client delay loop.

Working case

A reviewer creates inspection 93 for case 47. The database commits, but the browser loses the response and retries. The same key returns inspection 93 rather than creating inspection 94. If the note body changed between attempts while the key remained the same, the server responds with a conflict and asks for a new user intent. A simple process-local map demonstrates the decision rule, but production storage must keep key reservation and record creation in one transaction or another atomic boundary across workers.

Implementation

javascript
const attempts = new Map();
let nextInspectionId = 93;
function createInspection(reviewerId, caseId, key, note) {
  const scope = `${reviewerId}:${caseId}:${key}`;
  const previous = attempts.get(scope);
  if (previous) return previous.note === note ? previous.result : { status: 409 };
  const result = { status: 201, inspectionId: nextInspectionId++ };
  attempts.set(scope, { note, result });
  return result;
}
console.log(createInspection(29, 47, "review-47-19", "seal replaced").inspectionId);
console.log(createInspection(29, 47, "review-47-19", "seal replaced").inspectionId);
console.log(createInspection(29, 47, "review-47-19", "other note").status);

Observed output

Output
93
93
409

Cost and boundaries

An expected O(1) key lookup adds storage proportional to the number of retained keys, O(K). Hashing a request body of B bytes costs O(B). A transaction adds write latency but prevents a duplicate effect under concurrent retries. Retention expiry saves storage yet reopens the possibility of a duplicate after the window; document that tradeoff. Never key the cache only by an untrusted header without the authenticated caller and route, or two callers could receive each other's result.

Common Mistakes

  • Do not infer that a timed-out write had no effect.
  • Do not reuse one key for different request bodies.
  • Do not keep the key map only in one process when requests can reach several workers.

Connected lessons

Backend and API Systems; Cursor Pagination for Changing Collections; Background Jobs and the Outbox Boundary; Rate Limits and Request Budgets; HTTP requests: keep method, status, and body contracts separate; Form submission: validate on the server and return field errors; Routing: validate path parameters and return a stable error shape.

Failure trace

Two workers receive the same create request before either has written its in-memory key map. Both create an inspection, then both return success with different IDs. A lost response makes this race likely because the browser retries at exactly the uncertain moment. Reserve the key and commit the effect in one durable atomic boundary; bind the stored request fingerprint to the authenticated caller.

Verification

  • Send two concurrent requests with one key and assert both responses identify one stored record.
  • Reuse the key with a changed body and assert a conflict without a new record.
  • Drop the first response after commit, retry on another worker, and compare the returned record ID.

Decision note

A retry key should be scoped to one user intent and retained for a documented interval. After expiry, a delayed retry may create a second effect; expose that limit in the API contract instead of hiding it.

Apply and check

Build Project: paginated inspection feed with safe writes; then check the boundary with Web Development: data and API contracts quiz.

Further connections

Conditional Writes and Lost-Update Prevention; Request Deadlines, Retries, and Backoff.

Further connections

Hosted Checkout Sessions and Browser Returns; Payment Webhook Reconciliation and Idempotent Fulfillment.

web-tech
web-development
Storage details