Bind the key to the intended operation
Generate one stable key for a business operation before its first submission and retain it across transport retries. At the submission boundary, scope the key to the customer and bind it to a fingerprint of the normalized request, including contract version and destination connection.
The same key and same request should resolve to the original run. Reusing the key with a different request should produce a conflict, not silently apply new instructions to an old operation. A key must not act as authorization to retrieve another customer’s result.
| Submission | Handling |
|---|---|
| Same key, same operation | Return or continue observing the original run. |
| Same key, changed input | Reject the conflicting request. |
| New key, same supplier invoice | Apply business duplicate detection independently. |
| Lost write response | Reconcile the original destination operation first. |
An invoice can be duplicated under a new key
Request idempotency cannot detect every duplicate business transaction. A caller can upload the same invoice twice with different keys, or send equivalent documents with different file hashes. The business check needs an agreed identity such as supplier and normalized invoice number, plus rules for credit notes, corrections, and legitimate reuse.
Amount differences should not automatically turn a suspected duplicate into a new invoice. They may indicate a correction or extraction error. The contract must define the exception path instead of letting the model choose a convenient identity.
Close the race at the write boundary
Two concurrent runs can both observe that no bill exists. A preliminary duplicate query therefore cannot replace atomic protection at the destination. A connector design should establish whether it can enforce a unique external reference, use native idempotency, or serialize the relevant operation.
If the destination provides no reliable way to prevent or identify duplicate writes, that is an integration limitation. It should be documented before enabling autonomous mutation. A fresh fallback model does not provide stronger write isolation.
Specify retention before clients depend on it
An idempotency window must be long enough for the supported retry and reconciliation paths. Expiration behavior needs to be explicit: an expired key must not accidentally be understood as proof that the underlying invoice is new.
Record the key length, normalization and fingerprint rules, retention duration, and concurrent-request behavior in the integration agreement. Define how completed operations remain discoverable and how clients should recover after the idempotency window expires.
Missing a detail or found a problem?
Send a documentation question →