What you build yourself
Two things most people expect from an official SDK are not in any Lockally client, in any language. Both are straightforward to write, and both are worse to discover in production.
| Retries and backoff | Nothing is retried, including 429 |
| Webhook signature verification | No helper exists; you implement the HMAC |
They are absent for the same reason: the clients are generated from an OpenAPI specification, and neither behaviour can be derived from one.
Retries
The practical risk is 429. Your per-minute rate cap is real, bursty
workloads hit it, and a client that treats 429 as a hard failure drops mail
it could simply have sent a moment later.
What to implement:
- Retry on
429, on5xx, and on network errors. - Never retry
4xxother than429. The request is wrong, and repeating it wastes the attempt. - Honour
Retry-Afterwhen present. On429the API sends it, and it is a better number than any backoff you would compute. - Otherwise exponential backoff with jitter. Without jitter, everything that failed together retries together.
- Cap the attempts. Three to five is plenty; beyond that you are queueing, and a queue is a different design.
A sketch, in TypeScript:
async function sendWithRetry(body: SendEmailRequest, key: string) {
const maxAttempts = 4;
for (let attempt = 1; ; attempt++) {
try {
return await api.sendEmail({ idempotencyKey: key, sendEmailRequest: body });
} catch (err) {
const status = (err as ResponseError).response?.status;
const retryable = status === 429 || (status && status >= 500) || status === undefined;
if (!retryable || attempt === maxAttempts) throw err;
const header = (err as ResponseError).response?.headers.get('retry-after');
const wait = header
? Number(header) * 1000
: Math.min(2 ** attempt * 250, 8000) * (0.5 + Math.random());
await new Promise((r) => setTimeout(r, wait));
}
}
}
Note key is a parameter, not generated inside. That is the whole safety
property.
Webhook signature verification
Every webhook carries a signature header. Verifying it is what stops anyone who learns your endpoint URL from posting fabricated delivery events at it.
No client implements this. The algorithm is documented at Signature verification, and that page is the reference. Three things to get right, none of which a generated client would have helped with:
Use the raw request body. Compute the HMAC over the exact bytes received, before any JSON parsing. A framework that parses and re-serialises changes the bytes and every signature then fails.
Compare in constant time. hmac.compare_digest, crypto.timingSafeEqual,
subtle.ConstantTimeCompare, or your language’s equivalent. A plain ==
leaks timing.
Enforce the timestamp. Reject anything outside a few minutes, or a valid old request can be replayed at you indefinitely.
Pagination
Lesser, but the same shape: list endpoints return next_cursor and no client
iterates for you. Loop until it is absent, and guard the loop so a bug cannot
spin forever. See Pagination.