Delivery and retries
What counts as a successful delivery, how failed deliveries are retried, and when an endpoint is switched off.
Successful delivery#
A delivery succeeds when your endpoint answers with any 2xx status within 10 seconds. The
response body is ignored.
| Your endpoint | Result |
|---|---|
2xx within 10 seconds | Delivered. |
5xx, 408, 425 or 429 | Failed — retried. |
| Timeout, connection refused, DNS or TLS error | Failed — retried. |
Any other 4xx | Failed — not retried. |
A redirect (3xx) | Failed — not retried. Redirects are never followed. |
Retries#
A failed delivery is retried up to 6 attempts in total, waiting longer each time:
| Attempt | Sent after the previous one |
|---|---|
| 1 | — |
| 2 | 10 seconds |
| 3 | 20 seconds |
| 4 | 40 seconds |
| 5 | 80 seconds |
| 6 | 160 seconds |
- Localoy → Your endpoint: Attempt 1
- Your endpoint → Localoy: 503 Service Unavailable
- Note: Wait 10 seconds
- Localoy → Your endpoint: Attempt 2 — new t and v1, same event ID
- Note: No answer in 10 s — timeout
- Note: Wait 20 seconds
- Localoy → Your endpoint: Attempt 3
- Your endpoint → Localoy: 200 OK — delivered
All six attempts fall within about five minutes. Each retry carries a fresh timestamp and
signature, the same X-Localoy-Event-Id, and an incremented X-Localoy-Delivery-Attempt.
After the last attempt fails, the delivery is marked failed. It stays in the portal's delivery log, where you can replay it once your endpoint is fixed.
Delivery guarantees#
- At least once. An event may arrive more than once — for example when your endpoint processed it
but the response was lost. De-duplicate on
X-Localoy-Event-Id. - No ordering guarantee. Retries mean a later event can arrive before an earlier one. Use
occurredAt, or read the current state, rather than relying on arrival order.
Automatic disabling#
Localoy counts consecutive failed attempts — retries included — for each endpoint. When the count reaches 10, the endpoint is switched to disabled and stops receiving new events. Any successful delivery resets the count to zero.
Because retries count, an endpoint that is down while about two events are delivered can be disabled.
To recover:
- Fix your endpoint.
- Press Test in the portal to confirm it answers — Test works on a disabled endpoint.
- Enable the endpoint again. This resets its failure count.
- Replay the deliveries that failed while it was down.
Delivery log#
The Partner Portal lists every delivery with its status, the number of attempts, the payload, and — for the latest attempt — your endpoint's HTTP status, the start of its response, the error if there was one, and how long it took. A pending delivery also shows when it will next be tried.