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.

      Authentication errors

      Every authentication failure is application/problem+json and carries a request_id. The title distinguishes the cases.

      The 401s

      All four mean “we did not accept your credential”, and the detail says why.

      Missing Bearer token

      No Authorization header at all.

      {
        "type": "about:blank",
        "status": 401,
        "title": "Missing Bearer token",
        "detail": "Provide an API key (lk_live_...) or admin session token (adm_sess_...) in the Authorization header.",
        "request_id": "d728bad6-e5d5-4153-a355-34b8621d7ff4"
      }

      Usually the header is spelled wrong, or the Bearer word is missing. The format is Authorization: Bearer lk_live_....

      Malformed API key

      The header was there but the value is not shaped like a key. The detail gives the expected shape and what it got:

      apikey: malformed key: expected format: lk_live_<8-char-prefix>_<32-char-secret>
      (or lk_test_...) (got prefix=8 secret=31)

      Nearly always truncation: a secret store that clipped the value, a copy that missed the last character, or a shell that ate something. The character counts in the message are the fastest way to confirm it.

      Invalid API key

      The key is well formed but we will not accept it. Three details distinguish the reasons:

      detail Meaning
      Key not recognised. No key on any account matches
      Secret does not match. Wrong secret
      Key mode (live/test) does not match its registration. A live key sent as lk_test_, or the reverse

      The third is the interesting one: it means your environments are crossed, and the request failed loudly instead of a staging deployment mailing real people. See live and test keys.

      Revoked API key

      The key existed and was retired. The detail carries the date:

      {
        "status": 401,
        "title": "Revoked API key",
        "detail": "This key was revoked on 2026-10-17T09:41:02Z"
      }

      Worth handling separately in your alerting, because unlike the others it means something you deployed is holding a key you deliberately retired. Compare the date against your rotation records.

      The 403s

      A 403 means we know who you are and the request is still not allowed.

      Insufficient scope

      {
        "status": 403,
        "title": "Insufficient scope",
        "detail": "This endpoint requires scope: send:write",
        "code": "insufficient_scope"
      }

      The detail names the scope. Because a key’s scopes are fixed at creation, the fix is a new key, not an edit.

      Business mode required

      {
        "status": 403,
        "title": "Business mode required",
        "code": "business_mode_required"
      }

      The endpoint needs hosted mailboxes and the account does not have them. Adding the scope will not help: there is nothing for it to act on. Add business mail in the console, or use a different endpoint.

      Upgrade required

      The account’s plan does not include API keys. Checked on every request, so this can start appearing without anything in your code changing, after a plan change or a failed payment.

      It is the most machine-readable refusal the API sends, carrying extension members so your application can react rather than just log:

      {
        "status": 403,
        "title": "Upgrade required",
        "detail": "API keys available on the Starter and Pro plans.",
        "reason": "plan",
        "feature": "api_keys",
        "available_on": ["Starter", "Pro", "Scale"],
        "upgrade_plans": ["Starter", "Pro"]
      }

      reason: "plan" is the reliable discriminator: it marks every plan refusal, on this endpoint and any other gated one. available_on lists every plan with the feature, upgrade_plans the ones that would be an upgrade from where the account is now.

      Telling them apart quickly

      You see It means Do
      401 Missing Bearer token header absent fix the header
      401 Malformed API key value is the wrong shape check for truncation
      401 Invalid API key unaccepted key check which key, and which environment
      401 Revoked API key retired key still deployed deploy the current key
      403 Insufficient scope wrong scopes issue a key with the scope
      403 Business mode required wrong product not a scope problem
      403 Upgrade required plan lacks API access check billing

      Quote the request id

      Every response carries request_id, in the body and in the X-Request-Id header. It is the one thing that lets support find your exact call, including the failures, so capture it from error bodies and include it when you ask.

      You may also send your own X-Request-Id and we will echo it back, so one trace can run through your logs and ours. It is accepted when it is at most 64 characters of letters, digits, dots, hyphens and underscores, and quietly replaced with a generated one otherwise.