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.

      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.