Concepts

Delivery and retries

How Kestrel decides a delivery failed, and the exact schedule it retries on.

Delivery and retries

What counts as success

A delivery succeeds when your endpoint returns any 2xx status within the response timeout. Everything else — a 4xx, a 5xx, a connection reset, a TLS error, a timeout — is a failed delivery.

Redirects are not followed. A 301 or 302 is recorded as a failed delivery, so point subscriptions at the final URL.

Timeouts

Kestrel waits 10 seconds for response headers. The clock starts when the request is written, not when the connection is opened, so a slow TLS handshake does not eat into it.

The retry schedule

A failed delivery is retried up to 5 times with exponential backoff and full jitter. The base delay is 2 seconds and the cap is 32 seconds.

Timeline of delivery attempts with 2s, 4s, 8s, 16s and 32s gaps — Six attempts in total: the initial delivery plus five retries, roughly a minute end to end.

Attempt	Nominal delay after previous attempt
1 (initial)	—
2	2s
3	4s
4	8s
5	16s
6	32s

After the sixth attempt the delivery is marked exhausted and no further attempts are made. The event itself is untouched — you can still replay it.

Jitter means the delays above are upper bounds, not exact times. Do not build logic that assumes a retry lands at a particular second.

Circuit breaking

If an endpoint fails 20 consecutive deliveries, Kestrel disables the subscription and emails the account owner. Deliveries queued while a subscription is disabled are held for the plan's retention window and can be replayed once you re-enable it.

Re-enable a subscription from Dashboard → Subscriptions, or with:

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

Idempotency

Retries reuse the event id, so your endpoint will see the same id more than once whenever a response is lost after you processed it. Deduplicate on id.

const seen = await redis.set(`kestrel:${event.id}`, '1', 'NX', 'EX', 60 * 60 * 24);
if (!seen) return res.sendStatus(200); // already handled

A 24-hour dedup window comfortably covers the retry schedule, which finishes within about a minute of the first attempt.

Replay

Any delivery inside your retention window can be replayed. Replays are recorded separately and do not count against the original delivery's attempt budget.

See Handling failures for the operational playbook.

What counts as success

A delivery succeeds when your endpoint returns any 2xx status within the response timeout. Everything else — a 4xx, a 5xx, a connection reset, a TLS error, a timeout — is a failed delivery.

Redirects are not followed. A 301 or 302 is recorded as a failed delivery, so point subscriptions at the final URL.

The retry schedule

A failed delivery is retried up to 5 times with exponential backoff and full jitter. The base delay is 2 seconds and the cap is 32 seconds.

Six attempts in total: the initial delivery plus five retries, roughly a minute end to end.

Attempt

Nominal delay after previous attempt

1 (initial)

—

16s

32s

After the sixth attempt the delivery is marked exhausted and no further attempts are made. The event itself is untouched — you can still replay it.

Jitter means the delays above are upper bounds, not exact times. Do not build logic that assumes a retry lands at a particular second.

Circuit breaking

Re-enable a subscription from Dashboard → Subscriptions, or with:

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

Idempotency

Retries reuse the event id, so your endpoint will see the same id more than once whenever a response is lost after you processed it. Deduplicate on id.

const seen = await redis.set(`kestrel:${event.id}`, '1', 'NX', 'EX', 60 * 60 * 24);
if (!seen) return res.sendStatus(200); // already handled

A 24-hour dedup window comfortably covers the retry schedule, which finishes within about a minute of the first attempt.