Retries and dead letters
When an endpoint fails, Kestrel retries with backoff, then parks the event in a dead-letter queue, so nothing is lost and one bad endpoint never holds up the rest.
How retries work
Events now move to the dead-letter queue after three failed attempts. Before v2.4 they were retried for up to 24 hours.
A delivery fails when the endpoint answers with anything other than a 2xx, takes longer than 15 seconds, or can't be reached. Each retry waits longer than the last, with jitter so a recovering endpoint isn't hit by every event at once.
An endpoint that answers 410 Gone is disabled straight away and its pending events are dead-lettered.
The dead-letter queue
Dead-lettered events keep their payload, every attempt and the last error for 7 days. List them per endpoint to see what went wrong.
const parked = await kestrel.deadLetters.list({
endpointId: "ep_8fK21",
limit: 20,
});
for (const letter of parked.data) {
console.log(letter.eventId, letter.lastError);
}Replaying events
- 1Fix the endpoint, or wait until your customer confirms it's back.
- 2Open Deliveries, filter by Dead-lettered, and select the events to send again.
- 3Choose Replay. Each event is delivered once more and counted as a new attempt.
await kestrel.deadLetters.replay("dl_3Hc9Ve");A replayed event may land after newer events for the same object. Compare the event's created timestamp before overwriting state.