Retries and Failures

A delivery that does not succeed is retried on a fixed backoff schedule. This page describes exactly what counts as a failure, how long we keep trying, and what happens when we stop.

What counts as a failure

Anything that is not a 2xx response inside the 10-second budget:

a 4xx — including 401 and 404
a 5xx
a connection error, TLS failure, or DNS failure
no response within 10 seconds

A 3xx is also a failure. We do not follow redirects. A destination URL that redirects — to https, to a trailing slash, to a new path — will never receive a delivery, and every attempt will be retried and then dead-lettered. Register the final URL, not one that redirects to it.

The retry schedule

Eight attempts in total:

Attempt	Sent after the previous one
1	— (immediately)
2	10 seconds
3	1 minute
4	5 minutes
5	30 minutes
6	2 hours
7	6 hours
8	12 hours

Each gap carries up to ±20% jitter, so that a batch of deliveries failing at the same moment does not come back in lockstep. End to end the schedule spans roughly 21 hours.

A single successful 2xx ends the sequence — there are no further attempts for that event.

When attempts run out

After the eighth failed attempt the event is dead-lettered: we stop trying and record the failure. It is not delivered later, and there is no queue that drains once your endpoint recovers.

Because the schedule spans about 21 hours, an outage shorter than that is normally absorbed without losing anything — the later attempts arrive after you are back.

Suspension

After five consecutive dead-lettered events, the subscription is suspended automatically. Deliveries stop entirely, including events that would have succeeded.

This protects both sides from an endpoint that has gone away: it stops us hammering a dead URL for every order, and it stops a silent misconfiguration from being mistaken for quiet traffic.

Reinstating a suspended subscription is a Komplett action — contact your Account Manager once your endpoint is healthy again. Events that occurred while the subscription was suspended are not backfilled; reconcile them through the Orders API.

Designing for this

Return 2xx before you process. Acknowledge as soon as the event is queued on your side. Slow work inside the request is indistinguishable from a broken endpoint, and a timeout costs you seven more copies of the same event.
Deduplicate on eventId. Retries re-send the same event with the same id. Keep processed ids for longer than the 21-hour window. This protects you against a redelivery of one event, not against several different events describing a single change — those carry different ids and are not duplicates. See Follow an order lifecycle.
Do not infer ordering from arrival. Each event retries independently and every gap is jittered, so a later event can easily land before an earlier one.
Re-fetch resource.href when you process. It returns current state, not a snapshot from when the event fired — so a retry that arrives 12 hours late still gives you a correct answer.