> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackshift.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Best Practices

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

<Tip>
  **Live.** This area is documented as current, user-reliable behavior.
</Tip>

## Goal

Avoid the most common reliability mistakes.

## Prerequisites

* A Durable Jobs flow in progress

## Workflow

<Steps>
  <Step>
    Use idempotency keys for every externally triggered job.
  </Step>

  <Step>
    Keep job handlers idempotent.
  </Step>

  <Step>
    Break workflows into named steps.
  </Step>

  <Step>
    Use correlation keys that identify the exact resource waiting for an event.
  </Step>

  <Step>
    Avoid long blocking work that should be an event wait or separate step.
  </Step>
</Steps>

## 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

<Check>
  Your jobs are safer to retry, easier to observe, and easier to resume.
</Check>