Skip to main content
Live. This area is documented as current, user-reliable behavior.

​
Goal

Configure retries without repeating completed side effects.

​
Prerequisites

  • A job with side effects wrapped in named steps

​
Workflow

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

​
Automatic retries

Set retry attempts
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.

Observability

Inspect each job run through status, attempts, logs, payload, result, errors, and timeline.

Idempotency

Use idempotency keys so duplicate requests do not create duplicate work.