Skip to content
PayloadPuffin.
Join the waitlist

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.

The delivery states: pending moves to delivering, which ends in delivered on a 2xx, or moves to retrying while attempts remain and to failed after the last one. A held or failed delivery returns to retrying when you resend it.

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:

AttemptWaits after the previous attempt
1No wait
25 seconds
35 minutes
430 minutes
52 hours
65 hours
710 hours
810 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

You can't choose a different retry schedule for a destination yet. Every destination uses the schedule above.

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 is delivered.
  • 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-After response 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.