Idempotency - Threadify Documentation

Idempotency prevents retries from recording the same step more than once.

Idempotency Approaches

Approach	When to Use	Key Generation
Auto-generated (default)	Context uniquely identifies operation	Hash of `stepName + context`
Manual (`.idempotencyKey()`)	External system IDs, user-initiated retries, cross-service deduplication	Custom key (e.g., payment providers payment ID, request ID)

// Auto-generated (default)
await thread.step('validate_cart')
  .addContext({ items: '3', total: '99.99' })
  .success();

// Manual key with external ID
const payment = await payments.charges.create({ amount: 9999 });
await thread.step('charge_payment')
  .idempotencyKey(payment.id)
  .addContext({ amount: '99.99' })
  .success();

// Auto-generated (default)
_, err := thread.Step("validate_cart").
    AddContext(map[string]any{"items": "3", "total": "99.99"}).
    Success(ctx)
if err != nil {
    log.Fatal(err)
}

// Manual key with external ID
payment, err := payments.Charges.Create(&payments.ChargeParams{Amount: 9999})
if err != nil {
    log.Fatal(err)
}
_, err = thread.Step("charge_payment").
    IdempotencyKey(payment.ID).
    AddContext(map[string]any{"amount": "99.99"}).
    Success(ctx)
if err != nil {
    log.Fatal(err)
}

# Auto-generated (default)
await (
    thread.step("validate_cart")
    .add_context({"items": "3", "total": "99.99"})
    .success()
)

# Manual key with external ID
payment = await payments.charges.create(amount=9999)
await (
    thread.step("charge_payment")
    .idempotency_key(payment.id)
    .add_context({"amount": "99.99"})
    .success()
)

An execution grant supplies an invocation ID for its report, distinguishing separate permitted attempts. Outside that flow, use an explicit key when distinct operations have identical step names and context. Deduplication of reports does not make the external payment or tool call idempotent.

Best Practices

Use a stable business identifier, such as an order or payment ID, for retries.
Never reuse a key for a different operation.