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.

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

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:

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.

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.

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

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:

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.