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.
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.
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
| Approach | What it gives you | Right when | What it costs |
|---|---|---|---|
Retry, no key | The simplest client | The operation is idempotent already: | A retried |
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
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.