Idempotency and recovery

Create requests never update or match existing records, so a request sent twice creates two records. To retry safely after a timeout or a network error, give each intended create an idempotency key and reuse it for every retry.

Interface	Where the key goes
REST	Idempotency-Key request header
MCP	operation_key tool argument

How to use a key

1. Before sending, generate a new key for the record you intend to create, such as a UUID, and save it with your own data.
2. Send the create with that key.
3. If you get no response, a timeout, a 5xx, 409 operation_in_progress or 429, send the same body with the same key again, waiting for Retry-After when it's present, with backoff otherwise.
4. Once you have a 201, store the record ID and stop retrying.

Never switch to a new key just because a response was lost. A new key means a new record.

How the server treats a key

Situation	Result
New key	The record is created: 201, Idempotency-Replayed: false (MCP: replayed: false).
Same key, same body, within 7 days	The original result is returned again. No second record is created and no create allowance is used: 201, Idempotency-Replayed: true (MCP: replayed: true).
Same key, different body	409 idempotency_key_reused. Nothing is created.
Same key while the first request is still running	409 operation_in_progress with Retry-After.
Same key more than 7 days later	409 idempotency_window_expired. Keys can never be reused for a different record.

• Keys are 16–128 printable ASCII characters.
• "Same body" means the same JSON value. Property order and whitespace don't matter, but leaving a field out differs from sending its default: a body without description doesn't match one with "description": null.
• Keys are scoped to the organization, the connection, the identity behind it (for MCP, the person who approved the connection) and the kind of record. Rotating a token keeps the scope. The same key on a different connection is a different request and creates another record.
• Replays are authorized again. If the connection has lost a permission since the first request, the replay is rejected rather than returned.
• Without a key, the server generates one and returns it in the Idempotency-Key response header (MCP: operation_key in the result). That protects retries only if you receive the response, so always send your own key.

Recover the outcome

Every successful create returns an operation: the Operation-Location header in REST, operation_id in MCP. Read it with Get an operation or fieldtask_get_operation to confirm what was created and to check follow-up work.

A 201 means the record is saved. Follow-up work, such as geocoding an address or synchronization with a connected system, runs separately, is reported on the operation, and never removes the record.

After seven days

Retained results and operations expire seven days after the create. After that:

• Replaying the key returns 409 idempotency_window_expired.
• Reading the operation returns 410 operation_result_expired.

Neither means the create failed. Reconcile with the record ID you saved, or with an external reference, before creating anything new.