Errors

Errors are JSON with a stable machine-readable error code and a human message:

{ "error": "plan_limit_reached", "message": "Your plan allows 1 application set(s)…" }

The SDKs map these to typed exceptions. Only 429 is retried by the SDKs — everything else is a decision the service already made, so handle it, don't retry it.

Common codes

HTTP	error	Meaning
400	validation_failed	Request body failed validation (see fields).
401	invalid_credentials	Wrong email/password.
401	invalid_refresh_token	Refresh token unknown or malformed.
401	refresh_token_expired	Refresh token past its lifetime — re-authenticate.
401	refresh_token_reused	A rotated token was replayed; the session family is revoked. Re-authenticate.
401	invalid_token / invalid_token_use	Access token invalid, or a management token used where an audience token was required (or vice-versa).
403	account_not_active	The user, or an org above them, is disabled/suspended.
403	access_denied	Authenticated, but missing the required permission.
400	unknown_audience	The audience doesn't match a registered application.
400	unknown_organization	Referenced organization doesn't exist or isn't reachable.
402	plan_limit_reached	Application-set cap reached — see Plans & limits.
409	(conflict)	E.g. a plan downgrade that current usage doesn't fit.
429	(rate limited)	Back off; the SDKs retry this one for you.

MFA and reset

error	Meaning
invalid_code	Wrong TOTP / recovery code.
invalid_or_expired_pending_token	The short-lived MFA continuation token lapsed — log in again.
invalid_or_expired_reset_token	Password-reset link expired or already used.

note

Codes are contractual and safe to branch on. The message is for humans and may change — don't parse it.