Errors
{ "error": "<code>", "message": "…" }, the code from the klock errorcatalog (
KlockErrorCode). Older routes answer { "error": "<sentence>" }.WWW-Authenticate: Klock error="<code>".Shared responses
| Response | What it means |
|---|---|
Accepted | Taken, not done. The operation is where the answer will appear. |
Unauthorized | No token, a token that no longer verifies, or a session that was signed out |
Forbidden | Your role cannot do that |
PlanLimit | The account's plan does not allow this. The body names the limit, what is in use, what it would become, and which plans would take it. |
AdminOnly | This route is admin-only: the account is not an admin, the admin is holding an assumed identity, or the session was handed off to the customer console ({ error: "<sentence>" }). With enforcement E3 on, also mfa_required — an admin with no confirmed TOTP second factor — whose body says where to enrol (see MfaRequired). |
TooManyRequests | Rate limited. The auth routes get a strict budget, the data plane its own per-minute one keyed by api key, and everything else a shared one. |
ServiceUnavailable | Read-only mode (MAINTENANCE_MODE), or a dependency this route needs is not configured on this deployment. |
NotFound | No such thing, or none that is yours |
Conflict | It clashes with something that already exists |
ValidationError | The request body did not pass its rules |
KlockUnauthorized | Not authenticated. For a bearer, the token is missing, expired or signed out. For Authorization: Klock, the grant, the signature or the session was refused: grant_invalid, grant_expired, signature_invalid, clock_skew, nonce_replayed, session_revoked, device_key_mismatch. |
CapabilityMissing | capability_missing — the session, the key or the caller's team role does not carry the capability this route needs. Only answered where the area's enforcement mode is enforce (a team role is always checked). |
StepUpRequired | step_up_required — the route (or the capability, when it is only dormant) needs a fresh step-up. 401 with WWW-Authenticate: Klock error="step_up_required" for a klock session, 403 for a bearer. |
SessionFrozen | session_frozen — the klock session is frozen until it is unfrozen; or lockdown — the account is locked down. |
LoginV2Required | login_v2_required — with enforcement E3 on (CAPABILITY_E3), no new v1 CLI bearer tokens are issued from the login flow. Sign in with prorm login (a klock v2 device session) instead. A personal token (purpose: token, 30 days at most) is still issued, and tokens already issued keep working until they expire. |
MfaRequired | mfa_required — with enforcement E3 on, every admin route needs the admin to have a confirmed TOTP second factor. The body says where to enrol (/security/mfa/setup, then /security/mfa/confirm); those routes are the account's own, so an admin is never locked out of them. |
KlockUnavailable | klock_v2_unavailable — this deployment has no klock signing keys or no published keyset, so v2 sessions cannot be issued or checked. |
AccessDenied | access_denied — an account, team or device access rule refused the request (/security/access-rules); or lockdown (423) when the account is locked down. |
KlockUnconfigured | klock_unconfigured — device management needs the klock service, and this deployment has no binding to it (or it is not configured); or klock_v2_unavailable — no signing key |
KlockServiceUnavailable | klock_service_unavailable — the klock service refused or did not answer |
DeviceCapabilityMissing | capability_missing — the session lacks device:read / device:manage (or is a service session), the team role lacks device:manage-members, or the device is the team owner's; assumed_identity — a change under an assumed identity; for a pairing, console_only. Checked in every enforcement mode. |
DeviceNotFound | device_not_found — no such device, or none the caller may act on; or Unknown team |
DeviceInvalidState | invalid_state — the device is in the wrong state for that (a revoked or wiped device cannot be wiped; only an active one rotates its key) |
ReasonRequired | reason_required — acting on someone else's device or session needs a reason (at most 500 characters) |
StaffActionBadRequest | reason_required (10–500 characters), or a refused stepUp proof: bad_request, mfa_not_enrolled, totp_required, password_browser_only |
StaffActionUnauthorized | Not signed in, step_up_failed, or — for a klock session — step_up_required (also when admin capabilities are still dormant) |
StaffActionForbidden | Not an admin, or the role lacks the support scope; mfa_required under E3 when the admin has no second factor; step_up_required for a bearer without a fresh step-up. |
StaffActionNotFound | not_found — unknown account; device_not_found — not a device of that account |
StepUpTooManyAttempts | too_many_attempts — too many step-up attempts; try again in a few minutes |
WouldLockYouOut | would_lock_you_out — the change would refuse your own current request. reasons says which rule and dimension; send force: true with a step-up to save it anyway. Forcing needs a verified email address (recovery: false when there is none). |
TeamRoleRefusal | capability_missing — your role on this team cannot do that (unlock: team-role, with yourCapabilities), or the session does not hold the capability; or the account is not verified yet. |
UnknownTeam | No such team, or you are not an active member of it |
TeamBillingRoleRefusal | capability_missing — the caller's role on the team cannot do that (unlock: team-role); or an account that is not verified, or a child's account, where the route spends |
UnknownTeamBilling | Unknown team — no such team, or one the caller is not an active member of (the same answer) |
StripeRefused | The payment provider refused the request |
BillingNotConfigured | Billing (or membership, or the usage price) is not configured on this deployment |
Modified at 2026-10-05 04:10:00