Skip to content
Get started
Get started
TCP DLQ Commands: Inspect, Retry, Purge
View Markdown
api reference · tcp · 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.

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[] }

Read aggregate DLQ health for a queue.

{ cmd: 'GetDlqStats', queue: string }
{ ok: true, data: { stats: DlqStats } }

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

With 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).


Clear all jobs from the dead-letter queue.

Request:

{ cmd: 'PurgeDlq', queue: string }

Response:

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

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.


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 }