Idempotency and retries

Which requests need a key#

Every timeline entry update or deletion and every timeline comment operation requires an Idempotency-Key, including comment creation, editing, replies, and deletion. These use the same 24-hour replay rules below.

Every asset, subscription, people, and location workflow write requires an Idempotency-Key. This includes notes, events, assignments, lifecycle actions, to-do writes, and location-space writes. Asset, person, and location image uploads and removals also require one. Every organization mutation requires one: settings updates, logo uploads/removals, and deletion. Every user and invitation write also requires one: permission changes, membership removal, and invitation creation, resend, or revocation. Every asset category, subscription category, and custom-field write requires one, including creation, updates, and deletion. Every asset event setup write also requires one, including display ordering. GET requests do not need one.

Idempotency-Key: 76969132-4a8d-4b97-982d-9fcb9c1d27c2

Use a unique key of 8–128 letters, numbers, dots, underscores, colons, or hyphens. A UUID is a convenient choice. Each endpoint page marks this header when required.

Retry the same action#

The server remembers successful workflow, inventory-image, organization, user, invitation, asset category, subscription category, asset event setup, and custom-field mutation responses for 24 hours per token, except for terminal organization deletion described below. A retry with the same token, HTTP method, path, body, and key returns the original response and status code with Idempotency-Replayed: true. The first success returns Idempotency-Replayed: false.

Keep the key together with your outbound request until its result is known. If a request times out, resend that request using its existing key. Do not generate a new key for a retry. A new action, record, or payload needs a new key.

Reusing a key for a different request returns 409 Conflict. Errors are not stored. After the 24-hour retention window, a reused key can execute the action again. A replacement token has a separate key history, so inspect the record before retrying an uncertain request with a different token.

For organization logo and inventory image uploads, the request fingerprint includes the file bytes, original filename, and MIME type. Keep all of them unchanged when retrying. Reusing the key with a different file or metadata returns 409.

User and invitation retries#

User permissions, membership removal, and invitation creation/resend/revocation use the same 24-hour replay rules. Removing a membership preserves the account and does not revoke the calling token because an integration cannot remove its creator. Removal and revocation can therefore replay a successful response after the target is gone.

Invitations use the Idempotency-Key header, not a request_id body field. A replay never sends another email or rotates an invitation link. Use a new key when intentionally resending an invitation. Authorization is rechecked before replay, so a revoked key or demoted creator cannot replay old results.

Category and field retries#

Category and custom-field writes use the same 24-hour replay rules. Successful deletions replay even after the category or field is gone. A create or update retry returns the original response even if the target was subsequently renamed or deleted. Fetch the category again when you need its current state. Permissions and current administrator access are checked before replay.

Timeline and comment retries#

Timeline entry updates, deletions, and comment operations remember successful responses for 24 hours per token. An identical retry replays the original result even though its version is now stale. The replay returns the original thread and versions, so GET the entry again if you need its current state. Required permissions and administrator access are rechecked before replay.

For a new comment operation, send both version and content_version from the latest entry GET. For a timeline PATCH or DELETE, send version. A stale version on a new action returns 409; refresh the entry and submit the revised request with a new key.

Organization deletion is terminal#

Deleting an organization requires a key, but successful deletion revokes the calling token and does not preserve a replay response. Any subsequent request using that token returns 401, including a retry with the same key. The successful response has data.deleted: true and data.token_revoked: true.

If the deletion response is lost, a 401 alone cannot distinguish successful deletion from another cause of invalid credentials. Verify the result through the app using any remaining account access before deciding what happened.

Inventory writes behave differently#

The base record endpoints, such as POST /api/v1/assets, PATCH /api/v1/people/{record}, and DELETE /api/v1/locations/{record}, do not implement this replay protection. Adding an Idempotency-Key header does not make them replayable. Each successful inventory POST creates another record. The dedicated /image endpoints are the exception and are replay protected.

After an uncertain inventory write, check whether the change already happened before submitting it again. Repeated subscription detail edits can also affect billing history. Prefer the dedicated billing workflow when you need an explicitly replayable billing action.

Handle conflicts and throttling#

A 409 can indicate a concurrent record change, invalid lifecycle state, an occupied location space, chronology conflict, or key reuse. Read the response message. Refresh the affected record and resolve the stated constraint. If you change the request, use a new key.

For a transient failure or 429, wait before retrying and retain the key for the same workflow request. Follow Retry-After when supplied and stay within the rate limits.