Skip to content

Sync queues and client idempotency

An outbox of unconfirmed changes, each tagged with a key minted once when the user acts, so a retry after a timeout or a closed tab doesn't apply twice. It's what makes an offline design safe to retry.

On this page

What it is

On this page, a sync queue means the client's outbox: an ordered, persisted list of the changes a user has made that the server hasn't confirmed yet. Client idempotency is the rule that makes that queue safe to retry: each change carries a unique value the client generated, and the server uses that value to recognize a later copy of the same request as a retry rather than a new action. The two go together because a queue exists to resend, and resending a plain POST is how duplicates get created.

The key side is well documented by payment APIs. Stripe's API accepts an Idempotency-Key header on POST requests; the client makes the key, and the docs suggest a version 4 UUID or another random string with enough entropy, up to 255 characters, with no personal data in it. For API v1, it keeps the first response (status and body) it produced for a key once the endpoint starts executing, and a retry with that key gets that stored response back, a 500 included. The parameters of the retry are compared with the original, and a mismatch is an error. Keys can be pruned after they are at least 24 hours old, after which the same key starts a new request.

The IETF's working draft for the Idempotency-Key header (revision 09, read in November 2026) describes the same shape as a general pattern: a UUID or similar random value is recommended, a server may store a fingerprint of the payload beside the key to catch a key reused with a different body and answer 422, and a retry that arrives while the original is still being processed should get a 409. It also notes that a client with no prior knowledge of the server can't assume the header will be honored, which is why a frontend design has to say what the server does with the key. In the browser, crypto.randomUUID() returns a v4 UUID, has been Baseline since March 2022, and is available in secure contexts.

The queue side is best seen in a sync engine. Replicache gives each local mutation a sequential integer id per client, persists the pending record so a closed tab doesn't lose it, and pushes pending mutations in batches in id order. The server runs them in that order and keeps a last-mutation-id high-water mark per client; when the client later pulls, it drops the pending mutations at or below that mark as confirmed and re-runs the rest on top of the fresh server state. A per-client sequence plays the role of the idempotency key here: with a record of the last id it applied, the server can tell a repeat from a new mutation.

ts
type Entry = { key: string; seq: number; op: string; args: unknown; attempts: number };
// Both predicates come from the API's own documentation of its statuses; there is no universal list.
declare function isFinal(status: number): boolean;     // the request itself is bad: don't resend it
declare function isRetryable(status: number): boolean; // documented as safe to resend with the same key
const MAX_ATTEMPTS = 8;

async function enqueue(op: string, args: unknown) {
  const entry: Entry = { key: crypto.randomUUID(), seq: nextSeq(), op, args, attempts: 0 };
  await db.transaction(['state', 'outbox'], async (tx) => {
    applyLocally(tx, op, args); // optimistic change
    tx.outbox.add(entry);       // same transaction: both land or neither
  });
  void drain();
}

let draining = false;
async function drain() {
  if (draining) return;
  draining = true;
  try {
    for (let head = await db.outbox.first(); head; head = await db.outbox.first()) {
      const res = await fetch(`/ops/${head.op}`, {
        method: 'POST', body: JSON.stringify(head.args),
        headers: { 'Idempotency-Key': head.key, 'Content-Type': 'application/json' },
      }).catch(() => undefined); // network failure: res is undefined
      if (res && res.ok) { await db.outbox.delete(head.key); continue; }
      if (res && isFinal(res.status)) { await rollBack(head); await db.outbox.delete(head.key); continue; }
      if (res && !isRetryable(res.status)) { await pauseQueue(head, res.status); break; } // let the app decide
      head.attempts += 1;
      if (head.attempts >= MAX_ATTEMPTS) { // move it out of the way so the rest can go
        await db.outbox.delete(head.key); await db.parked.add(head); continue;
      }
      await db.outbox.put(head);
      await sleep(backoff(head.attempts, res?.headers.get('Retry-After'))); // then the same head, same key
    }
  } finally { draining = false; }
}
window.addEventListener('online', () => void drain());

When to use it

Reach for an outbox when the app must accept writes while the network is absent or flaky: notes, to-do lists, messaging, field forms, anything a person uses on a train. The Background Synchronization API fits this case directly: the page registers a sync request under a tag, and the service worker gets a sync event with that tag once the device has connectivity, where it can send what's in the outbox. MDN lists it as limited availability and not Baseline, since it doesn't work in some widely used browsers, and it needs a secure context. So treat it as an improvement over a fallback, not the fallback itself: drain on app start, after each confirmed entry, and on the window's online event.

Don't gate the drain on navigator.onLine. MDN describes the property as unreliable: a connection to a local network counts as online with or without internet access, and on Windows the value depends on reaching a Microsoft server that firewalls or VPNs may block. Use it to label the UI as possibly offline, and let the actual request fail and back off to decide when to stop trying.

Use a key, with or without a queue, when the operation creates something and a person might retry it: a payment, a sent message, a new record. A connection error leaves the client not knowing whether the server ran the request, and the key is what lets it repeat the call without a second object being created. Pair it with a client-generated id for the object itself, as Replicache's example mutations do (createTodo with id: "t1", then markTodoComplete on t1): later entries in the queue can then reference the new object before the server has seen it.

When not to

Skip the key when the operation is idempotent already. Stripe's docs say to leave the header off GET and DELETE, where it has no effect because those requests are idempotent by definition, and a PUT of a full document behaves the same way. The thing to watch instead is ordering: a late retry of a PUT can land after a newer write and overwrite it, so a version number or If-Match check does more good there than a key. See Conflict resolution on the client.

Don't promise idempotency the server hasn't built. A client may send the header to express intent, but without prior knowledge it can't count on the server respecting it. If the backend you're given has no key store, say so, and make the operation idempotent some other way: put the client-generated id in the payload and let a unique constraint reject the second insert.

Don't silently replay changes that shouldn't run late. Key retention is finite on some servers: for API v1, Stripe may prune a key once it is at least 24 hours old, so a request whose first attempt went out, lost its response, and is retried after the key was pruned is processed as a new request. Separate from the key, a message composed on Monday may not be wanted on Wednesday. For high-stakes or time-sensitive actions, mark an entry that has waited past a limit you choose as stale in the outbox and ask the person before sending. And when losing unsent work on a reload is acceptable, an in-memory array with keys is a reasonable, smaller design; say that you chose it.

Compared

ApproachWhat it gives youRight whenWhat it costs

Retry, no key

The simplest client

The operation is idempotent already: PUT of a full document, DELETE

A retried POST creates duplicates; a late PUT can clobber a newer write

Key per request, no queue

A retry inside one session can't double-apply

An online app with occasional network blips and few writes

Unsent work is gone when the tab closes

In-memory queue with keys

Ordered retries while the page lives

Losing unsent changes on reload is acceptable and you say so

Gone on reload or crash

Persistent outbox (IndexedDB)

Pending entries persist past a closed tab; drains on reconnect

The app must accept writes offline

Head-of-line blocking; keys the server may have pruned while the entry waited

Service worker + Background Sync

Drains after the tab closes, when connectivity returns

Browsers that support it, with a drain-on-open fallback

Not Baseline; secure context required

Sync engine with mutation ids and rebase

Per-client order on the server; pending changes re-run on fresh state

Several devices or people edit the same data

Push and pull endpoints, and a data model the engine can diff

In a picture

Rename taskLocal stateOutbox: key k1

Step 1 of 4

The action lands locally and in the outbox

Someone renames a task. The client applies the change to local state and appends an entry to the outbox in the same transaction. The entry gets its key now, while it's created.

How to say it in an interview

The common mistake

Quiz

A queued change is retried three times before it succeeds. How many distinct idempotency keys should the server have seen for it?
When should the client delete an entry from the outbox?
The client retries an entry and gets a 409 saying a request with that key is still being processed. What's the right move?
The single write in the app is a PUT that replaces a user's whole settings document. What does a retry risk, and what helps most?

Related

Sources

  1. Stripe API reference: Idempotent requests
  2. IETF draft-ietf-httpapi-idempotency-key-header-09: The Idempotency-Key HTTP Header Field
  3. MDN: Background Synchronization API
  4. MDN: Crypto: randomUUID() method
  5. Replicache docs: How Replicache Works
  6. MDN: Navigator: onLine property
Sign in to report a mistake