> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hookstream.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Dead Letter Queue

DLQ flow, manual retry, and bulk retry for permanently failed events.

The dead letter queue holds events that exhausted every retry attempt. Instead of silently dropping them, hookstream flags them as permanently failed so you can inspect and retry on your own schedule.

## How an event reaches the DLQ

**Delivery fails**

A delivery attempt returns a non-2xx status or throws a network error.
  **Retries are scheduled**

The DeliveryScheduler schedules the next attempt based on the destination's [retry policy](/guides/retry-strategies).
  **Max attempts hit**

Once the attempt count reaches `retry_max_attempts`, the delivery is marked as DLQ: `is_dlq = true` and `dlq_at` is stamped.
  **An issue is opened**

Hookstream opens or updates an [issue](/guides/monitoring-alerts) grouping the failure with similar ones so you can triage in batches.

## Inspect DLQ events

Filter failed events anywhere you can filter events:

```bash curl
curl "https://hookstream.io/v1/events?status=failed" \
  -H "X-API-Key: $HOOKSTREAM_API_KEY"
```

```bash cli
hookstream events list --status failed
```

You can also open the Events page in the dashboard and set **Status = Failed**, or jump straight to the Issues page where related failures are already grouped.

Every failed event keeps its full history — status codes, latency, response headers, and error messages for each attempt.

## Retry DLQ events

```bash retry-one-event
curl -X POST https://hookstream.io/v1/events/evt_abc/retry \
  -H "X-API-Key: $HOOKSTREAM_API_KEY"
```

```bash retry-one-attempt
curl -X POST https://hookstream.io/v1/delivery-attempts/att_xyz/retry \
  -H "X-API-Key: $HOOKSTREAM_API_KEY"
```

```bash bulk-retry-issue
curl -X POST https://hookstream.io/v1/issues/iss_123/retry \
  -H "X-API-Key: $HOOKSTREAM_API_KEY"
```

Retries create new delivery attempts. The originals are preserved for audit, so your history stays intact.

Check the destination's [circuit breaker](/guides/circuit-breaker) before mass retrying. If the endpoint is still down, every retry just fails again and re-opens the breaker.

## Best practices

- **Alert on DLQ growth.** Create a `dlq` [alert rule](/guides/monitoring-alerts) so you notice before your customers do.
- **Use the Issues page for bulk work.** One `POST /v1/issues/:id/retry` handles every event in a group.
- **Look at error breakdown in Metrics.** Clusters of identical errors usually point at one fix that clears the whole queue.
- **Tune retries for flaky destinations.** If a destination reliably recovers within hours, extend `retry_intervals` so retries outlive transient outages.

## Next Steps

**[Retry Strategies](/guides/retry-strategies)**

Control how long an event retries before hitting the DLQ.
  **[Events API](/api/events)**

Programmatic access to events and delivery attempts.