Repeated writes | Faustine Docs

Deduplication of repeated writes keeps a write that a client sends twice from reaching your API twice. A model can retry after a timeout or a lost response, or call the same operation twice in one script. With deduplication on, the second call inside the window gets the response of the first, and your API is not called again.

Your API needs no change and the client sends nothing new. Deduplication is off by default and is turned on per environment.

How it works

Every write operation has identifying fields: the input fields that identify the record being written, such as email for crm.contacts.create. The analysis proposes them for operations that create records. An operation with no identifying fields uses all its input fields.

When a write is about to be sent to your API, the gateway computes a key from the environment, the credential, the operation, the connection and the values of the identifying fields. Two calls with the same key inside the window are the same write. The same write sent with another key, on another environment or to another connection is a different write.

Only writes are checked. Read operations are never deduplicated.

What the client gets

Situation	What the client gets	Your API
First call	The response of your API.	Called once.
Same input, inside the window, first call finished	The stored response of the first call. The log marks the call as replayed.	Not called.
Same input, first call still running or ended with an unknown outcome	A refusal with `idempotency_in_flight`.	Not called.
Same identifying fields, different values in the other fields	A refusal with `idempotency_conflict`.	Not called.
Same input, and the first response was larger than 64 KB	A refusal with `idempotency_duplicate`.	Not called.
Same input after the window	The response of your API.	Called again.

A response is stored only when your API answers with success. If your API answers with an error, or the connection is refused, the key is freed and a retry goes through. If the call times out or the connection drops, the gateway cannot know whether the write happened. It keeps the key until the window passes and refuses a repeat with idempotency_in_flight.

The refusal messages are written for the model. They name the identifying fields and say what to do next:

Denied (idempotency_conflict): "crm.contacts.create" with the same email executed 12 s ago with different values. To change that record use its update operation; if this is a different record, its identifying fields must differ.

Over MCP and inside run_code the call fails with that text. Over REST the response is 409 with the code in the body. See Gateway HTTP.

Turn it on

To deduplicate repeated writes in an environment:

In the portal, go to Agent Gateway and select your gateway.
Select the Policies tab.
Under Writes & Idempotency, turn on Deduplicate repeated writes.
In Window (seconds), enter a value between 1 and 86400. The default is 60.
Select Save changes.

Two identical writes further apart than the window are two writes.

Identifying fields

To see or change the identifying fields of an operation, open the API's Operations tab, select the operation, and edit Identifying fields. You can set more than one field. The fields belong to the API and apply to every gateway that serves it. See Operations.

Choose fields that are the same when the record is the same. With email as the identifying field, creating a contact twice with one email is one write, and creating two contacts with different emails is two.

What it does not do

The gateway does not retry a call. It only stops a repeat from reaching your API.
It does not turn a create into an update. To change a record, the client calls the update operation.
It does not replace confirmation. A write that requires confirmation is approved first and then checked like any other.
A recipe is not deduplicated as a whole. Each write the recipe makes is checked on its own. A write sent to every connection by fan-out routing is not checked.
A replayed call still counts against the credential's rate limit and quota.

If the gateway cannot check whether a write is a repeat, it lets the write through instead of blocking it.

Next steps

Confirmation: have a person approve a write before it runs.
Limits and quotas: the other policies of an environment.
Logs: find replayed and refused calls.