> For the complete documentation index, see [llms.txt](https://sonic-ai-works.gitbook.io/sonic-networks-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sonic-ai-works.gitbook.io/sonic-networks-docs/api-reference/idempotency-and-mutation-safety.md).

# Idempotency & mutation safety

Preview tenant-scoped idempotency, request fingerprinting, replay recovery, conflict handling and duplicate-safe mutation requirements for SONIC APIs.

**Status:** `Preview / Development`

Mutating operations use a durable uniqueness boundary equivalent to:

```
tenant / workspace scope
+ operation class
+ Idempotency-Key
= one logical mutation
```

Idempotency prevents a client timeout, mobile reconnect, browser retry, worker retry or duplicated provider callback from creating a second economic or provider-side effect.

## Required use

An `Idempotency-Key` is required for duplicate-sensitive mutations such as:

* generation dispatch;
* credit reservation/funding/settlement;
* checkout/payment intent creation;
* Marketplace order creation;
* reward allocation and claims;
* transaction-intent creation;
* Swap intents/submission/settlement;
* administrative policy publication;
* CCTP/x402 or other economic settlement operations.

## Request fingerprint

The server binds an idempotency record to the material request semantics. A recommended fingerprint includes normalized fields relevant to the operation, for example:

```
operation class
actor / tenant / workspace
resource identity
asset / mint
atomic amount + decimals
recipient
quote / policy identity
network
material payload hash
```

A key reused with materially different input must return a deterministic conflict such as `IDEMPOTENCY_CONFLICT`; it must never silently execute the new payload under the old identity.

## Retry semantics

A retry of the same logical request must not create:

* a second credit reservation;
* a second provider generation job;
* a second subscription or Marketplace charge;
* a second reward allocation/claim;
* a second transaction intent;
* a second settlement/reconciliation;
* a duplicate on-chain transaction.

Persist the durable operation ID and/or canonical result so clients can recover after timeouts.

```
client sends mutation
→ server creates durable operation
→ response is lost
→ client retries with SAME Idempotency-Key
→ server returns existing operation/result
```

A timeout is an **unknown client observation**, not proof that server execution failed.

## Concurrent requests

Two concurrent requests carrying the same idempotency identity must converge on one durable operation. The uniqueness constraint belongs in durable persistence, not only in process memory.

Process-local locks may reduce contention but cannot be the sole production guarantee in a multi-instance deployment.

## Response behavior

A successful replay should return the existing canonical resource/result or a recoverable state reference rather than repeat side effects.

Recommended metadata may include:

```json
{
  "meta": {
    "requestId": "req_xxx",
    "idempotencyKey": "idem_xxx",
    "replayed": true
  }
}
```

Clients must not infer economic settlement merely from `replayed: true`; they still inspect the operation's durable state.

## Lifecycle and retention

Idempotency records must live at least as long as the operation's safe-retry window and any provider/network ambiguity window relevant to that domain. Financial/settlement identities normally require durable retention aligned with audit and reconciliation policy rather than short in-memory TTLs.

## Canonical invariant

```
same tenant
+ same operation class
+ same idempotency key
+ same material request
= same logical operation
```

```
same key
+ materially different request
= reject conflict
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://sonic-ai-works.gitbook.io/sonic-networks-docs/api-reference/idempotency-and-mutation-safety.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.