Timeouts and server errors
What to retry
| Status | Retry? | |
|---|---|---|
| 400, 401, 403, 404, 409 | no | the same request fails the same way |
| 422 | no | Blocked by Data Loss Prevention, Mailbox not grantable |
| 429 | yes, after Retry-After |
the header is set where we know the window |
500 Internal error |
yes, with backoff | |
502 Queue error |
yes, with backoff | the message was not enqueued |
503 Billing not configured |
yes, slowly | a dependency is down, not your request |
| timeout, connection reset | yes, and see below |
Retrying a send is safe, and that is not luck
A timeout is the genuinely hard case: the request may have been accepted, and you cannot tell from your side. Retrying risks a duplicate; not retrying risks a lost message.
Idempotency-Key is required on both send endpoints precisely so this
decision is not yours to make. Replay the same request with the same key:
- if the first attempt was accepted, you get byte-exact the original response and no second message
- if it never landed, it is processed now
The dedupe window is 24 hours. So the correct behaviour on a timeout is to retry with the same key, not a fresh one. Generating a new key on retry is the bug this design exists to prevent, and it is the one people write.
Internal error is 977 call sites
That is not a figure of speech. Internal error is the single most common
problem title in the API, because every unexpected failure funnels to the same
handler rather than leaking an internal message to the caller.
Which means the body tells you nothing about the cause by design. The
request_id is the entire diagnostic, and it is the thing to quote.
{ "status": 500, "title": "Internal error", "detail": "",
"request_id": "9f2c1d84-..." }
Timeouts, from both ends
Ours. Handlers carry their own deadlines, commonly 5 to 15 seconds for
database work. A request that exceeds one answers 500, so from your side it
is an ordinary server error.
Yours. Set a client timeout well above a normal send, which completes in well under a second, and treat the timeout as retryable with the same idempotency key. A 5 second client timeout on a 30 MB attachment upload will fire while the request is still in flight and leave you retrying a send that was about to succeed.
Connection errors
A connection reset or a TLS failure usually means the request never arrived, but usually is not a guarantee, which is again why the idempotency key is the answer rather than a judgement call.
If every connection fails, check in this order: the host is
api.lockally.com; the scheme is HTTPS; your egress allows it; and the
system clock is right, because a badly skewed clock breaks TLS and the error
it produces names certificates rather than time.
Backoff
Exponential with jitter, starting around a second, capped at a minute, and a
total budget rather than unlimited attempts. Honour Retry-After when it is
present: on a rate cap it is 60, and on the daily allowance it is the number
of seconds to the next UTC midnight, which is a real number worth respecting
rather than retrying through.