Dead Letter Queue

What is the DLQ?

The dead letter queue (DLQ) records batches that could not be delivered, so you can see what failed, why, and which events were affected.

When a batch enters the DLQ

• All throughput.maxAttempts attempts failed with a retryable error (5xx, 408, 429, timeout, connection refused or reset). Reason: max_retries_exceeded
• The destination answered with a non-retryable result (other 4xx, 3xx, DNS or TLS errors). Reason: non_retryable_error

The batch's items are then removed from the buffer.

DLQ entry

{
  "dlqId": "8d3f6a2e-1b4c-4e7a-9c0d-5f2b1a3e4d6c",
  "customerId": "c_your_account",
  "projectId": "p_shop",
  "bufferId": "b_orders",
  "groupId": "b_orders:9a1c0b7e3d5f2a48:0",
  "groupKey": "cus_001",
  "reason": "max_retries_exceeded",
  "lastError": "HTTP 503",
  "attempt": 2,
  "itemCount": 3,
  "payloadSummary": {
    "messageIds": ["5b0c6f0e-…", "c2d8e1a0-…", "7f4b9e22-…"],
    "firstPayloadPreview": "{\"event\":\"order.created\",\"customerId\":\"cus_001\",…"
  },
  "createdAt": 1767225660000
}

attempt is zero-based (2 means the third attempt).

Retry and delete

Retry schedules an immediate delivery attempt for the entry's group and removes the entry. It delivers the items currently buffered for that group; because the failed items are not stored in the entry, they are not resent. Fix the root cause first, then replay missing events from your sender.

Delete removes the entry permanently.

Both require an admin or owner role.

Via dashboard

1. Open DLQ in the sidebar
2. Filter by buffer or reason, or search by group key or ID
3. Open an entry to see the last error and the payload summary
4. Click Retry or Delete

Via API

# List entries (optionally for one buffer; limit defaults to 100, maximum 500)
curl -H "X-API-Key: $WEBBU_API_KEY" \
  "https://webbu.dev/api/v1/dlq?bufferId=b_orders&limit=100"

# Get one entry
curl -H "X-API-Key: $WEBBU_API_KEY" \
  https://webbu.dev/api/v1/dlq/8d3f6a2e-1b4c-4e7a-9c0d-5f2b1a3e4d6c

# Retry
curl -X POST -H "X-API-Key: $WEBBU_API_KEY" \
  https://webbu.dev/api/v1/dlq/8d3f6a2e-1b4c-4e7a-9c0d-5f2b1a3e4d6c/retry

# Delete (204 No Content)
curl -X DELETE -H "X-API-Key: $WEBBU_API_KEY" \
  https://webbu.dev/api/v1/dlq/8d3f6a2e-1b4c-4e7a-9c0d-5f2b1a3e4d6c

Auto-pause

If dlqPauseThreshold batches in a row (default 3, configurable from 1 to 10) end up in the DLQ, Webbu disables the buffer to stop accepting events it can't deliver. While disabled:

• Ingest requests get 400 with "error": "Buffer is disabled", so your sender sees the failure and can apply its own retry policy
• Buffered items are not delivered

Any successful delivery resets the counter. To resume, fix the destination and re-enable the buffer: toggle Enabled in the dashboard, or:

curl -X PATCH https://webbu.dev/api/v1/admin/buffers/b_orders \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $WEBBU_API_KEY" \
  -d '{"enabled": true}'

Re-enabling resets the counter.

Best practices

• Check the DLQ after deploying changes to your endpoint
• Fix the root cause before retrying: the entry's lastError shows the status code or network error
• Return 5xx for temporary errors: 4xx responses are not retried and go straight to the DLQ