Lockally

      Use your API key in the examples

      Replaces lk_live_… in the code samples on this site so you can copy and run them. It is stored in this browser only and is never sent anywhere, including to Ask AI.

      It will be visible on the page. Use a test key if you are sharing your screen or taking screenshots.

      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, on 5xx, and on network errors.
      • Never retry 4xx other than 429. The request is wrong, and repeating it wastes the attempt.
      • Honour Retry-After when present. On 429 the 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.