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.

      Reading an error

      Every error is RFC 9457 application/problem+json. A real one, captured from the API:

      {
        "type": "about:blank",
        "status": 400,
        "title": "Missing Idempotency-Key",
        "detail": "All /v1/send calls require an Idempotency-Key header (any unique string per send, 24h dedupe window).",
        "code": "missing_idempotency_key",
        "request_id": "921f3d72-2618-4c05-a341-e29de4a385c6"
      }
      Field Branch on it?
      code yes, first machine-readable, derived from the title
      status yes the class of failure
      title for logs specific and human; code is the one to match
      detail no written for a person, wording changes
      request_id no keep it, quote it in support
      type no always about:blank

      The identifier to branch on

      Every error carries a code: a machine-readable identifier derived from the title at the single place problem documents are written.

      { "status": 403, "title": "Insufficient scope", "code": "insufficient_scope" }

      Branch on code. It is lowercase and underscore-separated, and a run of spaces or punctuation collapses to one separator, so Allow-list full and Allow list full produce the same code and always will.

      The full set is frozen in the repository and checked in CI, so an error that appears, disappears or is reworded shows up as a visible diff rather than a silent contract change.

      Titles are not the generic HTTP phrases

      Worth stating because it is the mistake the older version of our own error page made: the API does not return "title": "Bad Request" or "title": "Unauthorized". Titles name the specific failure.

      Status Examples of what you will actually see
      400 Invalid JSON body, Missing Idempotency-Key, Invalid variables, Attachment too large
      401 Missing Bearer token, Invalid API key, Revoked API key
      403 Insufficient scope, Business mode required, Upgrade required, Sender not authorised, Not allowed on a test key
      404 Not found, Mailbox not found, Domain not found, Message not found
      409 Address already in use, Alias address already exists, Account not active
      429 Too many attempts, Reply loop detected, plus the send rate cap
      500 Internal error
      502 Queue error
      503 Billing not configured

      Where to go next

      Symptom Page
      401 or 403 on the key itself Authentication errors
      400 on the body Bad requests
      the send was refused Rejected sends
      the attachment was refused Attachment errors
      429 Rate limits
      the same send happened twice Idempotency
      timeouts, 500s, connection resets Timeouts and server errors
      the template rendered wrongly Template errors
      your webhook signature will not verify Signature verification
      events are not arriving Reliability
      accepted but never delivered Debugging a failed request
      DNS will not verify DNS troubleshooting