Destinations go down. They deploy, they hit a rate limit, they return a 500 for a minute. So when an attempt fails, PayloadPuffin doesn't give up on the delivery. It waits and tries again, up to eight attempts in total, spread over more than a day.
PayloadPuffin stops on its own only at delivered and failed. A resend can start any delivery again, and the diagram shows the two cases that need one.
The schedule
The first attempt starts as soon as the event is processed and the destination has room for it. Each later attempt waits a fixed delay after the previous one completed:
| Attempt | Waits after the previous attempt |
|---|---|
| 1 | No wait |
| 2 | 5 seconds |
| 3 | 5 minutes |
| 4 | 30 minutes |
| 5 | 2 hours |
| 6 | 5 hours |
| 7 | 10 hours |
| 8 | 10 hours |
The delays add up to about 27 hours and 35 minutes. Each delay gets a random extra 0 to 20%, so deliveries that failed together don't retry together. The real window is therefore longer than the table, and the waits below can stretch it further.
Retry schedules per destination
What gets retried
Any attempt without a 2xx response is retried, with one exception. That includes 4xx responses, a network error, a timeout, and an attempt that PayloadPuffin itself couldn't prepare. A response that won't improve on a retry, such as a 410 Gone, is still retried on the same schedule until the eighth attempt.
The exception is a response that rejects the payload itself: 400, 413 and 422. Sending the same payload again gets the same answer, so by default the delivery fails on that attempt, after one attempt instead of eight. You can resend it. The receiver did answer, so the response doesn't count against the destination's circuit breaker or toward an automatic pause.
If your receiver rejects payloads for a while during a bad deploy, turn on Retry rejected payloads under Advanced in the destination's settings, or set "retryPayloadRejections": true with Update a destination. Those responses are then retried on the schedule above. The trade-off is up to eight attempts for every payload the receiver keeps rejecting. 429 and 408 are always retried.
When retrying stops
Retrying stops at the first of these:
- An attempt gets a
2xx. The delivery isdelivered. - The eighth attempt fails. The delivery is
failed. - An attempt fails in a way a retry can't fix, such as a transform output over 262,144 bytes. The delivery is
failed. - The event's retention ends. The delivery is removed with the event, in whatever state it was.
After failed, nothing happens on its own. Resend the delivery when the destination is ready.
Waits that are not retries
The schedule sets the earliest time for the next attempt. The destination can push it later:
- Receiver cooldown. An eligible
Retry-Afterresponse pauses requests across the destination, including new deliveries. A resend can bypass it. See Cooldown from Retry-After for the status exceptions and duration. - Repeated failures. An open circuit or automatic pause holds work while PayloadPuffin tests whether the receiver has recovered. Existing deliveries can still wait after recovery. See Delivery controls.
- Your own limits. The destination's concurrency and rate limits hold attempts back until there is room.
None of these waits records an attempt or uses one of the eight. Delivery controls covers the limits.
Late events are held, not retried
If PayloadPuffin processes an event more than 48 hours after it accepted it, the event's deliveries start held instead of pending. Nothing is attempted or retried. A held delivery waits for you to resend it.
Retries mean duplicates
A retry is a new request carrying the same event. If your destination did the work but its 2xx never reached PayloadPuffin, because of a timeout or a dropped connection, the next attempt delivers the same event again. Every attempt of a delivery has the same webhook-id header, so record the IDs you've processed and skip a repeat.