Documentation

Best Practices

Short rules for writing Durable Jobs that behave well in production.

Try StackShiftRead the overview

Search Docs

Durable Jobs

Best Practices

Live

Short rules for writing Durable Jobs that behave well in production.

Goal

Avoid the most common reliability mistakes.

Current status

Live

This area is documented as current, user-reliable behavior.

Workflow

  1. 1Use idempotency keys for every externally triggered job.
  2. 2Keep job handlers idempotent.
  3. 3Break workflows into named steps.
  4. 4Use correlation keys that identify the exact resource waiting for an event.
  5. 5Avoid long blocking work that should be an event wait or separate step.

Production checklist

  • Use idempotency keys for API requests, webhooks, payments, signups, imports, and provisioning.
  • Keep jobs idempotent even when StackShift is retrying for you.
  • Wrap side effects in step.run with stable step names.
  • Use correlation keys like user:user_123, order:order_123, or payment:pay_123.
  • Use waitForEvent for external waiting instead of sleeping or polling inside a running process.
  • Set explicit timeout behavior for waits.
  • Use state for progress, counters, temporary markers, and locks.
  • Watch the timeline before retrying manually.

Expected result

Your jobs are safer to retry, easier to observe, and easier to resume.