- Docs
- Reference
- TCP Protocol
- Dead Letter Queue
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
Section titled “DLQ Commands”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
Section titled “GetDlqStats”Read aggregate DLQ health for a queue.
{ cmd: 'GetDlqStats', queue: string }
{ ok: true, data: { stats: DlqStats } }RetryDlq
Section titled “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 retriedWith filter, the memory and SQLite engines retry every entry the filter selects
(honouring the filter’s own limit/offset) and ignore jobId and count. Only the
PostgreSQL backend combines them: it narrows to jobId when given, applies the filter,
and caps the result at count (falling back to filter.limit).
PurgeDlq
Section titled “PurgeDlq”Clear all jobs from the dead-letter queue.
Request:
{ cmd: 'PurgeDlq', queue: string }Response:
{ ok: true, count: number } // Number of jobs purgedRemoveDlqJob
Section titled “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
Section titled “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 }