# How do I make writes safe to retry?

Checked 2026-11-15 against GilbApp d5296208bbffa2ab70076e6194f5537c4be1ddf7.

Give each create a new Idempotency-Key, send the same request with that key again after a lost answer, and check for Idempotent-Replayed.

## Before you start

Your app creates records with POST /lws/vault/&lt;encoded vault id\>/c, as [the answer on creating a record in a vault](http://support.gilb.com/help/how-do-i-create-a-record-in-a-vault) shows.

## Steps

1. Make a new key for each create.

   Make a new key, such as the random unique text crypto.randomUUID\(\) gives, for each record you create, and keep it with that change until you have its answer.

   A key is 1 to 128 printable ASCII characters, space to \~, sent once. It names the request, not the record: the platform still makes the record's id. Use a key only for one request: the same body and the same Slug header \(the header that suggests the start of the new record's id\), if you send one. The order of the members in the JSON does not count.
2. Send the create with the key.

   Send the create with the header Idempotency-Key: &lt;the key\>; the answer is 201 with location and ETag, as without a key.

   An ETag is a fingerprint of the record's current state. Once access is checked, every answer to a request with a key carries Cache-Control: private, no-store \(a cache may not keep the answer\) and Vary: Authorization \(the answer depends on who asked\). Access is checked before the key, so a caller who may not write the vault gets the same 403 with or without one.
3. Send the same request again if the answer was lost.

   If the connection dropped, the app closed or no answer came, send the same request with the same key; the answer is 201 with Idempotent-Replayed: true and the same location and ETag, and no second record.

   201 without that header means no earlier try with this key made a record, because it did not arrive or it failed, or its key had run out: this is the first create, so store its answer. A key works for 24 hours after the first create; a retry does not make that longer. The replay does not look at the record: if it was changed or ended since, you still get the first answer.
4. Read the record before you send a change again.

   If the answer to a PUT, PATCH or DELETE was lost, GET the record: if it holds your change, it worked; if not, send the change again [with the ETag of that read](http://support.gilb.com/help/how-do-i-write-only-if-nothing-changed-if-match).

   Sending the same If-Match again \(the header that lets a write go through only if the record's ETag is still the one you send\) after the first try changed the record answers 412, because the record's ETag changed. A PUT of exactly the state the record already has answers 200, keeps the ETag and writes nothing. A DELETE sent again answers 404: treat it as done.

## Deeper

Also asked:

How do I make a create safe to retry after a timeout? Send the create with a new Idempotency-Key header, and after a timeout send the same request with the same key: the answer is 201 with Idempotent-Replayed: true, and no second record is made.

Other answers to a create with a key. 409 "IdempotencyKeyInFlight", with Retry-After: 1: a request with the same key is still being processed; nothing was made by this request, so wait and send the same request again. 409 "write\_conflict", with Retry-After: 0: the create met another write at the same moment; nothing was written and no key was kept, so send the same request with the same key. 422 "IdempotencyKeyReused": the key was used for a different body or Slug; nothing was made, and it is a fault in your app, so do not send it again with that key. 400 "IdempotencyKeyInvalid": "Idempotency-Key must be sent once." or "Idempotency-Key must be 1 to 128 printable ASCII characters."; send one key in that form. 403: you can no longer write the vault; stop. A 5xx answer, or none: nothing was kept for the key, so send the same request with the same key again.

A key belongs to you and to the vault you sent it to: another person, or you in another vault, using the same text has a separate key. A create that failed is not remembered, so the same key can still work on the next try. Two requests with the same key at the same moment make one record; the later one waits for the first and returns its answer.

Only POST /lws/vault/&lt;encoded vault id\>/c reads the key. POST /lws/c/&lt;id\> does not, so a retry there makes a second record: look for the first one before you retry there, and before any retry more than 24 hours after the first try. PUT /base/e/&lt;id\> writes at the id you give, so the same PUT again writes nothing new; POST /base/ingest finds a record made with exactly the same facts instead of making a second one.

The full reference is the Developer Guide, GilbPlatform's guide for people who build apps on it, in its chapter Dev.Guide.Sync, https://appbuilder.gilb.com/base/e/06gkzpwqkxz1h5002g87j1p3x0. It can be read with no sign-in, as data for programs and AIs rather than as a web page. The guide's chapter Dev.Guide.Writing still says there is no create-once header; the platform and Dev.Guide.Sync have one.

Source: GilbPlatform 498d29a0 \(live at https://id.gilb.com/version, read 2026-11-11; code read at 498d29a0\): src/lws/routes.ts:838-878 \(POST /lws/vault/:vaultId/c: the key read AFTER the vault resolver, :843-860, "a caller who may not write this vault gets the same 403 whether or not they sent a key"; 400 IdempotencyKeyInvalid; keyed create; the caching headers stamped only after the resolver\), :275-300 \(answerFromStored: 422 IdempotencyKeyReused "This Idempotency-Key was already used for a different request. Nothing was created."; replay 201 + idempotent-replayed: true, the first Location and ETag\), :301-346 \(keyedCreate: 409 IdempotencyKeyInFlight + Retry-After\), :979-997 \(POST /lws/c/:id: read\); src/lws/idempotency.ts:18 \(Retry-After 1\), :21 \(KEY\_PATTERN /^\[\\x20-\\x7e\]{1,128}$/\), :39-53 \(sent once; the two messages\), :65-72 \(request digest = path, Slug, body, canonical JSON\), :74-83 \(Cache-Control private, no-store; Vary Authorization\), :85-100 \(in-process queue\); src/write/idempotency.ts:16-45 \(the contract: a failed create keeps\), :56 \(24 h TTL\), :59 \(5000 ms wait across processes\), :79 \(scope = principal, vault, key\), :91-108 \(expired keys not found\), :118-148 \(claim in the record's own transaction\); src/lws/crud.ts:257 \(the key claimed inside lwsCreate's transaction\); src/server/app.ts:232-242 \(409 write\_conflict, Retry-After 0\); src/write/canonical.ts:33-55 \(JCS: member order does not count\); src/lws/crud.ts:300-380 \(PUT: If-Match checked first, so a stale tag is 412; 200 when unchanged :365\), :632-741 \(DELETE; an ended record is absent -\> 404, :642-657\); src/routes/write.ts:36-37, :103-104, :139 \(PUT /base/e/:id at the id given, 200 no-op when unchanged; POST /base/ingest mint-or-match; neither reads Idempotency-Key\); src/server/cors.ts:916-922, :1011-1018 \(idempotency-key allowed in, idempotent-replayed readable by a browser\). Dev.Guide.Sync \(A 06gkzpwqkxz1h5002g87j1p3x0, pack GilbPlatformDeveloperGuide, 2026-11-11 and; read for agreement, not copied\); Dev.Guide.Writing \(A 06gkzpwmgnzph1fb6jp7gf87c0, pack GilbPlatformDeveloperGuide, 2026-11-11 and; read for agreement, not copied\) Sync.RetryCreate \(the table and rules; verified on production 2026-10-21: replay, 422, five parallel requests, key length and form, Cache-Control and Vary; not verified: 403, 5xx, the live 409, 24-hour expiry, scope across people and vaults; its "Only this door" line says POST /base/ingest and PUT /base/e/&lt;id\> can make a second record: the code says they cannot, the page follows the code\); Writing.NoIdempotency \(still says "There is no create only once header yet": out of date, Guide fault G1\), .Put \(200 for the same state\), .Delete \(a second DELETE answers 404\). The code example is written here from the routes at 498d29a0, placeholders only. Rows: Developer.IdempotentRewrite, KeyedCreateRetry, IdempotencyKeyRefusals.

## For developers

### TypeScript: create-once.ts

```typescript
// Create a record once, even when an answer is lost. Make `key` once per create
// (crypto.randomUUID()) and keep it with the change until this returns.
// headersFor makes Authorization: DPoP <token> and a new DPoP proof for one method and address.
export async function createOnce(
  url: string, // https://<name>.gilb.com/lws/vault/<encoded vault id>/c
  body: { type: string; facts: Record<string, unknown> },
  key: string,
  headersFor: (method: string, url: string) => Promise<Record<string, string>>,
): Promise<{ location: string; etag: string | null; replayed: boolean }> {
  for (let attempt = 0; attempt < 5; attempt++) {
    let res: Response;
    try {
      res = await fetch(url, {
        method: "POST",
        headers: { ...(await headersFor("POST", url)), "content-type": "application/json", "idempotency-key": key },
        body: JSON.stringify(body),
      });
    } catch {
      await new Promise((resolve) => setTimeout(resolve, 1000));
      continue; // no answer: the same request, the same key
    }
    if (res.status === 201) {
      return {
        location: res.headers.get("location") ?? "",
        etag: res.headers.get("etag"),
        replayed: res.headers.get("idempotent-replayed") === "true",
      };
    }
    const answer = (await res.json().catch(() => ({}))) as { error?: string };
    const again = res.status === 409 && (answer.error === "IdempotencyKeyInFlight" || answer.error === "write_conflict");
    if (again || res.status >= 500) {
      const seconds = Number(res.headers.get("retry-after") ?? "1");
      await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
      continue;
    }
    // 400, 403, 422 and other refusals: do not send it again with this key.
    throw new Error(`create answered ${res.status} ${answer.error ?? ""}`);
  }
  throw new Error("no answer after 5 tries: keep the key and try again later");
}
```
