Your retry is not a fact

Every mutation says how to retry it

There is no single retry rule that applies to every operation, and pretending otherwise is how duplicates happen. Each public mutation publishes its own contract, and clients follow that contract rather than assuming.

Operations that declare Idempotency-Key bind the key to the authenticated actor and the canonical request body, and state whether the header is optional or required. The same key plus the same body replays the stored response without re-executing.

{
  "receipt": { "id": "rec_01JZ…A9", "oneTimeUsd": 14.00 },
  "replayed": true
}

replayed: true is how an agent knows it is looking at the first result rather than a second effect.

Bounded behaviour instead

A mutation that does not take Idempotency-Key documents its own bounded behaviour instead — a fresh onboarding session, a secret-bound idempotent poll, or unique-key deduplication. The point is that the semantics are written down and checkable, not that one mechanism is used everywhere.

Same key, different body. Reusing a key with a changed body is an error, not a silent overwrite. The binding is to the exact canonical request.

The ambiguous provider call

The riskiest retry is not the one your agent makes — it is the one SproutPad makes to a registrar after a timeout, when it genuinely does not know whether the order landed. Provider-adapter operations therefore accept internal idempotency keys, so retrying after an ambiguous result cannot silently duplicate provider work.

Where duplication still cannot be ruled out, the saga records the manual step needed rather than reporting success. See durable execution.

Keep reading