agmission/Development/server/docs/DLQ_API_REFERENCE.md

DLQ API Reference

Navigation: 📖 Index | 🚀 Quick Start | 📚 API Reference | 🔧 Operations | 🏗️ System Guide

---

Global Dead Letter Queue (DLQ) API for all queue types.

Base URL

/api/dlq/:queueName/*

Supported Queues:

• partner_tasks (or dev_partner_tasks in development)
• jobs (or dev_jobs in development)
• Any future queue types

---

Endpoints

1. Get DLQ Messages

Endpoint: GET /api/dlq/:queueName/messages

Peek at messages in the DLQ without consuming them.

Parameters:

• queueName (path) - Queue name (e.g., 'partner_tasks', 'dev_jobs')

Query Parameters:

• limit (optional) - Maximum messages to retrieve (default: 50)

Example:

curl -X GET "http://localhost:4100/api/dlq/partner_tasks/messages?limit=20" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "messages": [
    {
      "taskInfo": { "logFileName": "example.log", "partnerId": "..." },
      "errorMessage": "Connection timeout",
      "retryCount": 2,
      "enqueuedAt": "2025-12-19T10:30:00Z",
      "headers": { "x-retry-count": "2" }
    }
  ]
}

---

2. Get DLQ Statistics

Endpoint: GET /api/dlq/:queueName/stats

Get comprehensive statistics about a specific DLQ.

Parameters:

• queueName (path) - Queue name

Example:

curl -X GET http://localhost:4100/api/dlq/partner_tasks/stats \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "dlq": {
    "messageCount": 5,
    "consumerCount": 0,
    "queueName": "dev_partner_tasks_failed"
  }
}

---

3. Retry All DLQ Messages

Endpoint: POST /api/dlq/:queueName/retryAll

Retry all messages in the DLQ (or up to maxMessages).

Parameters:

• queueName (path) - Queue name

Body:

{
  "maxMessages": 100
}

Example:

curl -X POST http://localhost:4100/api/dlq/partner_tasks/retryAll \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"maxMessages": 50}'

Response:

{
  "success": true,
  "retriedCount": 50,
  "message": "Retried 50 messages from DLQ"
}

---

4. Retry by Position

Endpoint: POST /api/dlq/:queueName/retryByPosition

Retry messages by 0-based position range.

Parameters:

• queueName (path) - Queue name

Body:

{
  "startPosition": 0,
  "endPosition": 10
}

Example:

curl -X POST http://localhost:4100/api/dlq/partner_tasks/retryByPosition \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"startPosition": 0, "endPosition": 10}'

---

5. Retry by Header Match

Endpoint: POST /api/dlq/:queueName/retryByHeader

Retry messages matching specific header criteria.

Parameters:

• queueName (path) - Queue name

Body:

{
  "headerKey": "x-retry-count",
  "headerValue": "1"
}

Example:

curl -X POST http://localhost:4100/api/dlq/partner_tasks/retryByHeader \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"headerKey": "x-retry-count", "headerValue": "1"}'

---

6. Purge DLQ

Endpoint: DELETE /api/dlq/:queueName/purge

⚠️ DANGEROUS - Permanently delete all messages in the DLQ.

Parameters:

• queueName (path) - Queue name

Body:

{
  "confirm": true
}

Example:

curl -X DELETE http://localhost:4100/api/dlq/partner_tasks/purge \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"confirm": true}'

---

Multi-Queue Examples

Partner Queue

POST /api/dlq/partner_tasks/retryAll
GET  /api/dlq/partner_tasks/messages

Job Queue

POST /api/dlq/dev_jobs/retryAll
GET  /api/dlq/dev_jobs/messages

Future Queues

POST /api/dlq/notifications/retryAll
POST /api/dlq/analytics/retryAll

---

Authentication

All endpoints require admin authentication via Bearer token:

Authorization: Bearer YOUR_JWT_TOKEN

---

Error Responses

All error responses follow the project's standard error format with an error object containing a .tag field:

401 Unauthorized (AppAuthError):

{
  "error": {
    ".tag": "not_authorized"
  }
}

409 Bad Request (AppParamError):

{
  "error": {
    ".tag": "invalid_param",
    "message": "queueName parameter is required"
  }
}

500 Internal Server Error (AppError):

{
  "error": {
    ".tag": "unknown_app_error",
    "message": "Failed to connect to RabbitMQ"
  }
}

Note: The message field is only included in development mode. In production, only the .tag field is returned for security.

---

Related Documentation

📚 DLQ Documentation

• 📖 DLQ Index - Documentation overview
• 🚀 Quick Start - Get started in 5 minutes
• 🔧 Operations Guide - Advanced operations
• 🏗️ System Guide - Architecture details

🔗 Additional Resources

• Postman Collection - API testing
• Global DLQ Refactoring - Architecture changes
• Web Dashboard - Monitoring interface