Idempotency and retries

Which requests need a key#

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. 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 a successful workflow response for 24 hours per token. 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.

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.

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.