Guides

Handling failures

What to do when deliveries start failing, and how to get back to a clean state.

Handling failures

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

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

Triage

Deliveries are timing out

Signatures do not verify

The subscription was disabled

Events are arriving out of order

Replaying

Replay a single delivery:

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 within a time range:

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" }'

Bulk replay is rate limited per subscription to one call per minute on Free and Team and 20 calls per minute on Enterprise. 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:

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

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

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.