Skip to main content
Idempotency ensures that recording the same step multiple times has the same effect as recording it once. This prevents duplicate operations and ensures consistent execution when retries or network issues occur.

​
Idempotency Approaches

ApproachWhen to UseKey Generation
Auto-generated (default)Context uniquely identifies operationHash of stepName + context
Manual (.idempotencyKey())External system IDs, user-initiated retries, cross-service deduplicationCustom key (e.g., Stripe 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 stripe.charges.create({ amount: 9999 });
await thread.step('charge_payment')
  .idempotencyKey(payment.id)
  .addContext({ amount: '99.99' })
  .success();

​
Use Cases

ScenarioBehaviorExample
Network retriesSecond call with same key is ignoredPayment processing retry
Service restartsSame key returns existing resultService crashes mid-operation
Race conditionsOnly first request succeedsMultiple pods processing same order
Duplicate preventionPrevents duplicate charges/operationsUser clicks “Pay” twice

​
Best Practices

  • Use business identifiers (order ID, payment ID) when available
  • Follow consistent naming patterns for key generation
  • Ensure keys are unique within their scope
  • Never reuse idempotency keys for different operations

​
Next Steps

Tracking Workflows

Learn how to record steps in workflows

Handling Failures

Handle retries and failures properly