Skip to main content

Dead Letter Queue

Endpoints for managing the dead-letter queue (DLQ) — failed background tasks that have been captured for review and manual re-drive.

Base Path​

/admin/dead-letter

Authentication​

All endpoints require superadmin access.

Endpoints​

List Dead-Letter Tasks​

GET /admin/dead-letter

List failed tasks with optional filters.

Query Parameters

ParameterTypeDefaultDescription
statusstringnullFilter by status: failed, retried, expired
task_namestringnullFilter by task name
skipint0Pagination offset
limitint50Page size

Response 200 OK

{
  "items": [
    {
      "id": "...",
      "task_name": "run_quality_check",
      "error_message": "Connection timeout",
      "error_traceback": "...",
      "original_args": { "check_id": "..." },
      "retry_count": 3,
      "status": "failed",
      "created_at": "2026-02-27T15:00:00Z"
    }
  ],
  "total": 12
}

Get Dead-Letter Task​

GET /admin/dead-letter/{task_id}

Retrieve full details of a specific failed task including arguments, error context, and retry history.

Retry Dead-Letter Task​

POST /admin/dead-letter/{task_id}/retry

Re-enqueue a failed task for processing. The task is re-submitted to its original queue with the original arguments.

Response 200 OK

{
  "message": "Task re-enqueued successfully",
  "task_id": "...",
  "new_status": "retried"
}

Delete Dead-Letter Task​

DELETE /admin/dead-letter/{task_id}

Permanently remove a dead-letter entry.

Bulk Retry​

POST /admin/dead-letter/bulk-retry

Re-enqueue multiple failed tasks.

Request Body

{
  "task_ids": ["...", "..."]
}