Failed jobs, on the wire.

Inspect dead-letter entries with filters, read aggregate DLQ statistics, retry, purge or permanently remove failed jobs, and re-queue completed ones.

Part of the TCP protocol reference, which describes the framing, authentication, pipelining and response format that every command on this page uses.

A job is moved to the DLQ on demand with Discard, and per-queue DLQ settings are managed with SetDlqConfig / GetDlqConfig.

DLQ Commands

Dlq

Retrieve jobs from the dead-letter queue.

Request:

{
  cmd: 'Dlq',
  queue: string,
  count?: number,        // Max entries to return (optional)
  filter?: {
    reason?: string,
    olderThan?: number,
    newerThan?: number,
    retriable?: boolean,
    expired?: boolean,
    limit?: number,
    offset?: number
  }
}

Response:

{ ok: true, jobs: Job[], entries: DlqEntry[] }

GetDlqStats

Read aggregate DLQ health for a queue.

{ cmd: 'GetDlqStats', queue: string }

{ ok: true, data: { stats: DlqStats } }

RetryDlq

Retry jobs from the dead-letter queue (move them back to waiting).

Request:

{
  cmd: 'RetryDlq',
  queue: string,
  jobId?: string,        // Retry a specific job (optional; omit to retry all)
  count?: number,        // Cap the number of entries retried (omit = retry all)
  filter?: DlqFilter     // Retry only matching entries
}

Response:

{ ok: true, count: number }  // Number of jobs retried

PurgeDlq

Clear all jobs from the dead-letter queue.

Request:

{ cmd: 'PurgeDlq', queue: string }

Response:

{ ok: true, count: number }  // Number of jobs purged

RemoveDlqJob

Permanently delete one failed job without retrying it.

Request:

{ cmd: 'RemoveDlqJob', queue: string, jobId: string }

Response:

{ ok: true, data: { removed: boolean } }

removed: false is an idempotent miss. Persistence or handler failures return the normal { ok: false, error } response and must not be interpreted as a missing entry.

RetryCompleted

Re-queue completed jobs back to waiting state.

Request:

{
  cmd: 'RetryCompleted',
  queue: string,
  id?: string,           // Retry a specific job (optional; omit to retry all)
  count?: number,        // Non-negative cap
  timestamp?: number     // completedAt must be <= this epoch-ms cutoff
}

Response:

{ ok: true, count: number }