Errors

Every error is a problem detail with a stable code. Tell errors apart by the code, never by the text in detail, which may change. The SDKs map them to these exceptions (Java and .NET: …Exception; TypeScript and Python: …Error):

SDK exception	Codes
TenonAuthUnavailable (reason)	No connection (UNREACHABLE), no answer in time (TIMEOUT), a 5xx server error (SERVER_ERROR). Fail closed
ApiKeyRejected	unauthorized (401)
Forbidden	forbidden (403)
InvalidRequest (fields)	invalid_request and the other 400s
NotFound	not_found (404)
InvalidCode	invalid_code (422)
FactorLocked (lockedUntil)	factor_locked (429)
TooManyRequests (retryAfter)	too_many_requests (429)
EmailRefused	email_codes_not_allowed, email_domain_not_allowed, invalid_email, email_required
EmailUnavailable (challengeId)	email_unavailable (503)
Conflict (code)	The other 409s
TenonAuth	Anything else (e.g. push_not_configured)

Every code

Code	Status	Meaning
invalid_request	400	The request is malformed or a field is invalid; errors lists the fields
invalid_email	400	Not an email address
email_required	400	Email codes need an email address
invalid_ip_address	400	The sign-in context’s IP address is not an IPv4 or IPv6 address
invalid_username	400	(Console administrators) the username must be an email address
invalid_display_name	400	(Console administrators) the name must be 1–100 characters
unauthorized	401	No valid credential: the API key is missing, wrong or revoked
forbidden	403	The credential is valid but may not use this address
ip_not_allowed	403	(Tenon IT’s platform keys) not from this address
not_found	404	No such user, method or sign-in request in your organization
method_not_allowed	405	This address does not take this HTTP method
request_too_large	413	The request body is larger than 64 KB
wrong_factor_type	409	This method can’t do that (e.g. a code for sign-in approval)
factor_not_pending	409	The method is already active or was removed
factor_not_active	409	The method is not active (not set up yet, or removed)
enrollment_expired	409	The setup took too long or had too many wrong codes: start the setup again
challenge_not_pending	409	The sign-in request is already approved, denied, failed or expired
challenge_not_approved	409	The sign-in request was not approved
challenge_too_old	409	The sign-in was approved too long ago to remember the device
challenge_already_used	409	A device was already remembered with this sign-in
no_active_factor	409	The user has no active method, so there is nothing to recover
email_codes_not_allowed	409	Your organization’s Administrator does not allow email codes
email_domain_not_allowed	409	The address’s domain is not one your organization allows
organization_exists	409	(Tenon IT) an organization with this name exists
organization_claimed	409	(Tenon IT) the organization’s Administrator has signed in
username_taken	409	(Console administrators) that address is already an administrator
platform_key_exists	409	(Tenon IT) a platform key with this name exists
invalid_code	422	The code typed while setting up a method is wrong
factor_locked	429	Too many wrong codes: the method is locked until lockedUntil
too_many_requests	429	Too many requests or emails in a short time; try again after retryAfter
push_not_configured	503	Sign-in approval is not set up on this server
email_unavailable	503	No email could be sent. At sign-in, challengeId is still open for a recovery code

A wrong code at sign-in is not an error: verify answers verified: false with attemptsRemaining.