Skip to main content

​
Goal

Set up a queue consumer that retries on transient failures (e.g. an external endpoint being down) and automatically routes jobs to a dead letter queue (DLQ) when all retries are exhausted.

​
Steps

​
1. Register the external endpoint as an HTTP-invoked function

Register the payment API as an HTTP-invoked function. The engine makes the HTTP call — when the endpoint is down or returns a non-2xx status, the engine marks the invocation as failed. When this function is invoked via a named queue, the queue worker retries it based on the queue’s config.
payment-processor.ts
import { registerWorker } from 'iii-sdk'

const iii = registerWorker(process.env.III_URL ?? 'ws://localhost:49134')

iii.registerFunction(
  { id: 'payments::charge' },
  {
    url: 'https://api.payments.example.com/charge',
    method: 'POST',
    timeout_ms: 5000,
  },
)

​
2. Define a named queue with retry configuration

Declare the queue in iii-config.yaml with the retry and backoff settings. When the payment endpoint fails, the engine retries with exponential backoff until max_retries is exhausted — then the job moves to the DLQ. Enqueue work to this function by calling trigger() with TriggerAction.Enqueue from wherever the order is created.
iii-config.yaml
workers:
  - name: iii-queue
    config:
      queue_configs:
        payment_dlq:
          max_retries: 5
          backoff_ms: 2000
          concurrency: 2
          type: standard
      adapter:
        name: builtin
order-handler.ts
import { TriggerAction } from 'iii-sdk'

await iii.trigger({
  function_id: 'payments::charge',
  payload: { orderId: order.id, amount: order.total },
  action: TriggerAction.Enqueue({ queue: 'payment_dlq' }),
})
With this configuration, a failing job follows this timeline:
AttemptDelay before retry
12 s
24 s
38 s
416 s
5— moved to DLQ

​
3. What happens when a job lands in the DLQ

When the payment endpoint is down and all 5 retries exhaust, the engine:
  1. Removes the job from the active queue
  2. Stores it in the DLQ with the original payload, the last error, and a failed_at timestamp
  3. Logs a warning:
WARN queue="payment_dlq" job_id="..." attempts=5 "Job exhausted, moved to DLQ"
The job stays in the DLQ until the engine redrives it. No other jobs in the queue are blocked — processing continues normally for new messages.

​
4. Queue configuration reference

FieldTypeDefaultDescription
max_retriesu323Maximum delivery attempts before moving to DLQ
backoff_msu641000Base delay in ms between retries (exponential: backoff_ms × 2^(attempt − 1))
concurrencyu3210Max concurrent jobs for this queue
typestring"standard"Queue mode: "standard" (concurrent) or "fifo" (ordered)

​
Result

Failed jobs retry automatically with exponential backoff. After all retries exhaust, the job moves to the DLQ where it is preserved with its full payload and error context. The engine continues processing new messages in the queue without interruption.
DLQ is fully supported by the Builtin and RabbitMQ queue adapters. The Redis adapter does not support DLQ operations.