Documentation

Retries & Failure Handling

Durable Jobs retries transient failures, preserves completed steps, and gives failed work a clear recovery path.

Try StackShiftRead the overview

Search Docs

Durable Jobs

Retries & Failure Handling

Live

Durable Jobs retries transient failures, preserves completed steps, and gives failed work a clear recovery path.

Goal

Configure retries without repeating completed side effects.

Current status

Live

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

Workflow

  1. 1Set max attempts for retryable work.
  2. 2Let StackShift retry transient failures with backoff.
  3. 3Inspect failed runs and dead-lettered jobs.
  4. 4Manually retry when the cause has been fixed.

Automatic retries

Set retry attempts

ts
await stackshift.queue('payments').enqueue(
  'provisionAfterPayment',
  { paymentId: 'pay_123', customerId: 'cus_123' },
  {
    maxAttempts: 6,
    idempotencyKey: 'payment:pay_123:provision',
  }
)

Backoff and dead letters

  • Retries use exponential backoff so transient failures do not hammer dependencies.
  • After max attempts, the run is marked failed and can be routed to a dead-letter queue for inspection.
  • The run keeps error details, attempts, logs, and timeline entries.

Manual retry

  • Use manual retry after fixing the missing credential, dependency outage, bad payload, or external state.
  • Completed steps are reused when the job resumes, so successful side effects do not need to run again.
  • Use idempotency keys around external calls that may have succeeded before the failure was reported.

Expected result

Failures are visible, retryable, and safer because completed steps are remembered.