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.
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 requestRuns normally. A 2xx response (status, body and Location, ETag, Content-Type) is stored for 24 hours.
- Same key, same requestThe stored response comes back with Idempotent-Replayed: true. Nothing runs again.
- Same key, different request422. The method, path, query and body must match byte for byte. Use a new key for a new request.
- Same key, first one still running409 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 hoursThe key expires and the request runs as new.
What a key is scoped to
- TokenKeys belong to the token (or MCP grant) that sent them. Another token can use the same key string without colliding.
- CompanyThe token's company.
- Method and pathPOST /rest/v1.0/projects/7/rfis and POST /rest/v1.0/projects/8/rfis are separate scopes.
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 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.
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");
}