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.