Skip to content

Dead Letter Queue API

The Dead Letter Queue (DLQ) API provides endpoints for managing failed tasks, enabling retry, resolution, and monitoring of task processing failures. All endpoints require admin privileges.

Overview

CalcBridge's DLQ system supports:

  • Failed Task Tracking: Automatic capture of failed Celery tasks
  • Retry Mechanism: Retry individual tasks with optional force mode
  • Resolution Workflow: Mark tasks as resolved or discard them
  • Health Monitoring: DLQ statistics and health status

Admin Required

All DLQ endpoints require admin role privileges.

Endpoints

List DLQ Entries

Get a paginated list of DLQ entries with optional filtering.

GET /api/v1/dlq/entries

Query Parameters

Parameter Type Default Description
limit integer 50 Items per page (1-100)
offset integer 0 Pagination offset
status string - Filter: pending_review, retried, resolved, discarded
task_name string - Filter by task name
tenant_id string - Filter by tenant

Response

{
  "items": [
    {
      "dlq_id": "dlq_abc123",
      "original_task_id": "task_xyz789",
      "task_name": "src.workers.tasks.export.generate_export",
      "task_args": "[\"workbook_id\"]",
      "task_kwargs": "{\"format\": \"xlsx\"}",
      "exception": {
        "type": "ConnectionError",
        "message": "Database connection timeout",
        "traceback": "..."
      },
      "tenant_id": "t_abc123",
      "retries_attempted": 3,
      "failed_at": "2026-01-25T10:30:00Z",
      "processed_at": "2026-01-25T10:30:00Z",
      "status": "pending_review",
      "retry_count": 0,
      "last_retry_at": null,
      "retry_task_id": null,
      "resolved_at": null,
      "resolution_notes": null
    }
  ],
  "total": 5,
  "limit": 50,
  "offset": 0
}

Get DLQ Entry

Get details of a specific DLQ entry.

GET /api/v1/dlq/entries/{task_id}

Retry Failed Task

Retry a failed task from the DLQ.

POST /api/v1/dlq/entries/{task_id}/retry

Query Parameters

Parameter Type Default Description
force boolean false Force retry even if max retries exceeded

Response

{
  "original_task_id": "task_xyz789",
  "retry_task_id": "task_new123",
  "status": "retried",
  "message": "Task queued for retry"
}

Resolve DLQ Entry

Mark a DLQ entry as resolved.

POST /api/v1/dlq/entries/{task_id}/resolve

Request Body

Field Type Required Description
resolution_notes string No Notes about the resolution

Response

{
  "task_id": "task_xyz789",
  "status": "resolved",
  "resolved_at": "2026-01-25T11:00:00Z",
  "resolution_notes": "Data corrected and re-imported manually"
}

Discard DLQ Entry

Discard a DLQ entry permanently.

DELETE /api/v1/dlq/entries/{task_id}

Get DLQ Statistics

Get current DLQ statistics and health status.

GET /api/v1/dlq/stats

Response

{
  "timestamp": "2026-01-25T10:30:00Z",
  "total_failures": 25,
  "pending_entries": 5,
  "by_task": {
    "src.workers.tasks.export.generate_export": 3,
    "src.workers.tasks.calculate.recalculate": 2
  },
  "health": "warning"
}

Health Levels

Level Criteria
healthy 0 pending entries
warning 1-10 pending entries
critical >10 pending entries

Generate DLQ Report

Trigger immediate DLQ report generation.

POST /api/v1/dlq/report

Response

Returns the same DLQStatsResponse format.