Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.threadify.dev/llms.txt

Use this file to discover all available pages before exploring further.

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