Esc

↑↓ move↵ openIndex · Pagefind
Idempotency keys

Retry writes without doubling them.

Send an Idempotency-Key header on a POST, PUT, PATCH or DELETE. If the connection drops, send the same request with the same key: you get the first response back instead of a second record.

LiveProject and company write endpoints24-hour replay

How it works

Pick a unique key for each logical write: a UUID is ideal. The key is 1 to 255 visible ASCII characters; anything else returns 400. The key is checked after your token is authenticated, so a rejected token never stores anything.

  • First request
    Runs normally. A 2xx response (status, body and Location, ETag, Content-Type) is stored for 24 hours.
  • Same key, same request
    The stored response comes back with Idempotent-Replayed: true. Nothing runs again.
  • Same key, different request
    422. The method, path, query and body must match byte for byte. Use a new key for a new request.
  • Same key, first one still running
    409 with Retry-After: 1. Wait and send it again.
  • First request failed (4xx or 5xx)
    The key is released, so you can fix the request and send it again with the same key.
  • After 24 hours
    The key expires and the request runs as new.

What a key is scoped to

  • Token
    Keys belong to the token (or MCP grant) that sent them. Another token can use the same key string without colliding.
  • Company
    The token's company.
  • Method and path
    POST /rest/v1.0/projects/7/rfis and POST /rest/v1.0/projects/8/rfis are separate scopes.
First requestcurl
curl -X POST https://app.os.construction/rest/v1.0/projects/{project_id}/rfis \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a9e-3b7d-4c41-9a0e-2f5d8b1c7e44" \
  -d '{ "rfi": { "subject": "Fire dampers at grid C", "question": { "body": "Which damper model?" } } }'
# 201 Created: the RFI is saved and this response is stored for 24 hours
The retryhttp
# The connection dropped. Send exactly the same request again, same key:
HTTP/1.1 201 Created
Idempotent-Replayed: true
Content-Type: application/json

{ "id": 212, "number": "212", "subject": "Fire dampers at grid C", ... }
# Same body as the first response. No second RFI.

Where it works

Every project and company write endpoint under /rest accepts Idempotency-Key, and each one lists the header in the REST reference. A contract test in the app fails if a new write endpoint ships without it. Requests through the MCP connector pass the key through as idempotencyKey.

Accounting create and payment routes use their own key store, written in the same transaction as the posting, and keep keys for 30 days. On those routes a changed request returns 409 instead of 422. See Accounting API practices.

Limits to know

Only 2xx responses are stored. A response larger than 1 MB is recorded without its body: a retry then returns 409 and you read the record instead.

The stored response is saved right after the write commits. If the server stops in that moment, the key stays in progress and returns 409 until it expires, because the write may have happened. Check whether the record exists, then use a new key. A write is never repeated.

A retrying clientJavaScript
import { randomUUID } from "node:crypto";

// One key per logical write. Reuse it for every retry of that write.
export async function createOnce(url, body, token) {
  const key = randomUUID();
  for (let attempt = 0; attempt < 5; attempt++) {
    const res = await fetch(url, {
      method: "POST",
      headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", "Idempotency-Key": key },
      body: JSON.stringify(body), // same bytes every time
    }).catch(() => null);
    if (res && res.status !== 409 && res.status !== 429 && res.status < 500) return res;
    const wait = Number(res?.headers.get("Retry-After") ?? 0) * 1000 || 2 ** attempt * 500;
    await new Promise(r => setTimeout(r, wait));
  }
  throw new Error("gave up: check whether the record exists before writing again");
}

Ask the OS

Reading this page

Ask anything about this page. Answers use what you're reading as context.

Suggested

    AI · may be imperfect · sample data where shown

    Open file