Source: https://dinakar-pageloop-knowledge-base.docs-staging.pageloop.ai/guides/handling-failures

# Handling failures

# Handling failures

Start in **Dashboard → Deliveries**. Filter to the affected subscription and sort by status —
`exhausted` rows are the ones your system never received.

![](images/uploads/deliveries-dashboard.png)

_The deliveries view for a single subscription over the last 24 hours._

## Triage

#### Deliveries are timing out

Your endpoint is taking longer than the 10-second response timeout. Acknowledge first
and process afterwards — push the work onto a queue and return `200` immediately.

Check `durationMs` on recent deliveries to see how close you are to the limit.

#### Signatures do not verify

Almost always a raw-body problem: a body parser ran before your handler and the bytes
you hashed are not the bytes Kestrel signed. See [Signatures](/concepts/signatures).

The second most common cause is verifying against a rotated secret after the 24-hour
overlap has expired.

#### The subscription was disabled

Twenty consecutive failures disables a subscription. Fix the endpoint, re-enable, then
replay the held deliveries.

```bash
curl -X POST https://api.kestrel.dev/v1/subscriptions/sub_8213/enable \
  -H "Authorization: Bearer $KESTREL_API_KEY"
```

#### Events are arriving out of order

Ordering only holds for events sharing a `streamKey`. If you published without one,
there is no ordering guarantee. See [Events](/concepts/events).

## Replaying

Replay a single delivery:

```bash
curl -X POST https://api.kestrel.dev/v1/deliveries/dlv_01HZX9M4TT/replay \
  -H "Authorization: Bearer $KESTREL_API_KEY"
```

Or replay every exhausted delivery for a subscription in a time range:

```bash
curl -X POST https://api.kestrel.dev/v1/subscriptions/sub_8213/replay \
  -H "Authorization: Bearer $KESTREL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "exhausted", "since": "2026-08-20T00:00:00Z" }'
```

> [!WARNING]
>
> A bulk replay is rate limited to **one call per subscription per minute**, and each call
> queues at most 10,000 deliveries. Larger backfills need to be paged with `since`.

## Alerting

Kestrel emails the account owner when a subscription is disabled. For anything finer,
poll the metrics endpoint:

```bash
curl "https://api.kestrel.dev/v1/subscriptions/sub_8213/metrics?window=1h" \
  -H "Authorization: Bearer $KESTREL_API_KEY"
```

```json
{
  "window": "1h",
  "delivered": 8412,
  "failed": 37,
  "exhausted": 2,
  "p95DurationMs": 210
}
```

> [!TIP]
>
> Alert on `exhausted`, not `failed`. A failed delivery that later succeeds on retry is
> normal background noise; an exhausted one is data your system never received.