errmodel

package
v0.147.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 30, 2026 License: MIT Imports: 4 Imported by: 0

Documentation

Overview

Package errmodel is AuthKit's one error model: the catalog fixing every wire code's HTTP status and message, the concrete error value, and its constructors. Hosts see these values only through iam.Error.

Index

Constants

This section is empty.

Variables

View Source
var (
	CodeTwoFAEnrollmentRequired           = def("2fa_enrollment_required", 403, "Two-factor authentication must be enrolled to continue.")
	CodeTwoFAFactorExists                 = def("2fa_factor_exists", 409, "A two-factor authentication method is already enrolled. Remove it before enrolling a replacement.")
	CodeTwoFAMethodUnavailable            = def("2fa_method_unavailable", 400, "That two-factor method is unavailable.")
	CodeTwoFARequired                     = def("2fa_required", 403, "Two-factor authentication is required.")
	CodeAccessTokenHasSub                 = def("access_token_has_sub", 401, "An access token must not carry a subject.")
	CodeAccessTokenWrongTyp               = def("access_token_wrong_typ", 401, "The token type is wrong for an access token.")
	CodeAccountAuthorityEscalation        = def("account_authority_escalation", 403, "That account holds authority you do not.")
	CodeAccountDisabled                   = def("account_disabled", 401, "This account is disabled.")
	CodeAccountExistsLinkRequired         = def("account_exists_link_required", 409, "An account with this email already exists. Sign in and link the provider.")
	CodeAccountRecoveryExpired            = def("account_recovery_expired", 409, "The account recovery window has ended.")
	CodeAccountRecoveryRequired           = def("account_recovery_required", 409, "Confirm account recovery before signing in.")
	CodeAddressMismatch                   = def("address_mismatch", 400, "The address does not match.")
	CodeAddressRequired                   = def("address_required", 400, "An address is required.")
	CodeAPIKeyExpired                     = def("api_key_expired", 401, "The API key has expired.")
	CodeAPIKeyInvalid                     = def("api_key_invalid", 401, "The API key is invalid.")
	CodeAPIKeyNotFound                    = def("api_key_not_found", 404, "The API key was not found.")
	CodeAPIKeyRevoked                     = def("api_key_revoked", 401, "The API key has been revoked.")
	CodeAuthRequiredForLink               = def("auth_required_for_link", 401, "Sign in before linking a provider.")
	CodeAuthenticationFailed              = def("authentication_failed", 401, "Authentication failed.")
	CodeAvatarURLInvalid                  = def("avatar_url_invalid", 400, "The avatar URL is invalid.")
	CodeBadAudience                       = def("bad_audience", 401, "The token audience is not accepted.")
	CodeBadIssuer                         = def("bad_issuer", 401, "The token issuer is not trusted.")
	CodeBootstrapDatabaseNotEmpty         = def("bootstrap_database_not_empty", 409, "The database is not empty; bootstrap refused.")
	CodeCannotTargetSelf                  = def("cannot_target_self", 403, "You cannot perform this action on yourself.")
	CodeCannotUnlinkLastLoginMethod       = def("cannot_unlink_last_login_method", 400, "The last login method cannot be unlinked.")
	CodeChallengeExpired                  = def("challenge_expired", 401, "The challenge has expired.")
	CodeChallengeMismatch                 = def("challenge_mismatch", 401, "The signed message does not match the challenge.")
	CodeChallengeNotFound                 = def("challenge_not_found", 401, "The challenge was not found or was already used.")
	CodeCodeExpired                       = def("code_expired", 401, "The code has expired or was used up. Request a new one.")
	CodeConfirmationWrongTokenType        = def("confirmation_wrong_token_type", 401, "This token type does not accept a confirmation claim.")
	CodeConflictingSubject                = def("conflicting_subject", 401, "The token carries conflicting subjects.")
	CodeContactNotVerified                = def("contact_not_verified", 409, "The email address or phone number is not verified.")
	CodeDelegatedAccessHasRoles           = def("delegated_access_has_roles", 401, "A delegated token must not carry roles.")
	CodeDelegatedAccessHasUserTier        = def("delegated_access_has_user_tier", 401, "A delegated token must not carry a user tier.")
	CodeDelegatedAccessWrongTyp           = def("delegated_access_wrong_typ", 401, "The token type is wrong for delegated access.")
	CodeDelegationAuthorizerUnavailable   = def("delegation_authorizer_unavailable", 503, "Delegation is unavailable.")
	CodeDelegationRefused                 = def("delegation_refused", 403, "The delegation was refused.")
	CodeDeviceKeysDisabled                = def("device_keys_disabled", 403, "Device keys are disabled.")
	CodeEmailAlreadyVerified              = def("email_already_verified", 409, "The email address is already verified.")
	CodeEmailDeliveryFailed               = def("email_delivery_failed", 502, "The email could not be delivered.")
	CodeEmailInUse                        = def("email_in_use", 400, "That email address is already in use.")
	CodeEmailUnavailable                  = def("email_unavailable", 503, "Email is unavailable.")
	CodeEntitlementFilterUnavailable      = def("entitlement_filter_unavailable", 400, "Entitlement filtering is unavailable.")
	CodeExternalInvitesDisabled           = def("external_invites_disabled", 403, "Invite links are disabled.")
	CodeForbidden                         = def("forbidden", 403, "You do not have permission to perform this action.")
	CodeGroupConflict                     = def("group_conflict", 409, "The group id is taken by a deleted group or a group of another persona.")
	CodeGroupNotFound                     = def("group_not_found", 404, "The group was not found.")
	CodeInsufficientAuthority             = def("insufficient_authority", 403, "You do not have the authority for this operation.")
	CodeInternalError                     = def("internal_error", 500, "An internal error occurred. Please try again.")
	CodeInvalidTwoFAMethod                = def("invalid_2fa_method", 400, "The two-factor method is invalid.")
	CodeInvalidAddress                    = def("invalid_address", 400, "The address is invalid.")
	CodeInvalidAudiences                  = def("invalid_audiences", 400, "The audiences are invalid.")
	CodeInvalidBootstrapManifest          = def("invalid_bootstrap_manifest", 400, "The bootstrap manifest is invalid.")
	CodeInvalidChallenge                  = def("invalid_challenge", 401, "The challenge is invalid.")
	CodeInvalidCode                       = def("invalid_code", 401, "The code is invalid.")
	CodeInvalidConfirmation               = def("invalid_confirmation", 401, "The confirmation claim is invalid.")
	CodeInvalidCredentials                = def("invalid_credentials", 401, "Invalid credentials.")
	CodeInvalidDelegateCertificate        = def("invalid_delegate_certificate", 400, "The delegate certificate is invalid.")
	CodeInvalidDomain                     = def("invalid_domain", 401, "The signed domain is invalid.")
	CodeInvalidEmail                      = defParam("invalid_email", 400, "email", "The email address is invalid.")
	CodeInvalidExpiry                     = def("invalid_expiry", 400, "The expiry is invalid.")
	CodeInvalidIdentifier                 = def("invalid_identifier", 400, "The identifier must be an email address or a phone number.")
	CodeInvalidInvite                     = def("invalid_invite", 400, "The invite is invalid.")
	CodeInvalidLink                       = def("invalid_link", 400, "The link is invalid or has expired.")
	CodeInvalidMessageEncoding            = def("invalid_message_encoding", 400, "The message encoding is invalid.")
	CodeInvalidPassword                   = def("invalid_password", 401, "The password is incorrect.")
	CodeInvalidPhoneNumber                = defParam("invalid_phone_number", 400, "phone_number", "The phone number is invalid.")
	CodeInvalidPreferredLanguage          = defParam("invalid_preferred_language", 400, "preferred_language", "The preferred language is invalid.")
	CodeInvalidProvider                   = def("invalid_provider", 400, "The provider is invalid.")
	CodeInvalidRemoteApplication          = def("invalid_remote_application", 400, "The remote application is invalid.")
	CodeInvalidRequest                    = def("invalid_request", 400, "The request is invalid.")
	CodeInvalidRequestedGrant             = def("invalid_requested_grant", 400, "The requested grant is invalid.")
	CodeInvalidServiceJWT                 = def("invalid_service_jwt", 401, "The service token is invalid.")
	CodeInvalidSignature                  = def("invalid_signature", 401, "The signature is invalid.")
	CodeInvalidSignatureEncoding          = def("invalid_signature_encoding", 400, "The signature encoding is invalid.")
	CodeInvalidState                      = def("invalid_state", 400, "The state is invalid.")
	CodeInvalidTimestamp                  = def("invalid_timestamp", 401, "The signed timestamp is invalid.")
	CodeInvalidToken                      = def("invalid_token", 401, "The authentication token is invalid.")
	CodeInvalidUI                         = def("invalid_ui", 400, "The ui parameter is invalid.")
	CodeInvalidUntil                      = def("invalid_until", 400, "The until value is invalid.")
	CodeInvitationExpired                 = def("invitation_expired", 400, "The invitation has expired.")
	CodeInvitationNotFound                = def("invitation_not_found", 404, "The invitation was not found.")
	CodeInvitationRevoked                 = def("invitation_revoked", 400, "The invitation was revoked.")
	CodeIssuerKeysUnavailable             = def("issuer_keys_unavailable", 503, "The token issuer's signing keys are temporarily unavailable.")
	CodeLastOwner                         = def("last_owner", 409, "The last owner cannot be removed.")
	CodeMalformedPermissions              = def("malformed_permissions", 401, "The permissions claim is malformed.")
	CodeMissingAudience                   = def("missing_audience", 401, "The token carries no audience.")
	CodeMissingDelegatedSub               = def("missing_delegated_sub", 401, "The delegated token carries no subject.")
	CodeMissingExp                        = def("missing_exp", 401, "The token carries no expiry.")
	CodeMissingFields                     = def("missing_fields", 400, "Required fields are missing.")
	CodeMissingIAT                        = def("missing_iat", 401, "The token carries no issued-at.")
	CodeMissingKID                        = def("missing_kid", 401, "The token names no key.")
	CodeMissingName                       = def("missing_name", 400, "A name is required.")
	CodeMissingNBF                        = def("missing_nbf", 401, "The token carries no not-before.")
	CodeMissingSessionID                  = def("missing_session_id", 400, "A session id is required.")
	CodeMissingSidClaim                   = def("missing_sid_claim", 400, "The token carries no session.")
	CodeMissingSub                        = def("missing_sub", 401, "The token carries no subject.")
	CodeMissingTokenTyp                   = def("missing_token_typ", 401, "The token carries no type.")
	CodeNameAdmissionRefused              = def("name_admission_refused", 403, "That name was refused.")
	CodeNoSession                         = def("no_session", 401, "No session is signed in.")
	CodeNotDelegatedAccessToken           = def("not_delegated_access_token", 401, "The token is not a delegated access token.")
	CodeNotFound                          = def("not_found", 404, "The requested resource was not found.")
	CodeNotImplemented                    = def("not_implemented", 501, "Not implemented.")
	CodeOIDCBeginFailed                   = def("oidc_begin_failed", 400, "The provider login could not be started.")
	CodeOIDCExchangeFailed                = def("oidc_exchange_failed", 401, "The provider login could not be completed.")
	CodePasskeyCloneDetected              = def("passkey_clone_detected", 401, "The passkey appears to have been cloned.")
	CodePasskeyNotFound                   = def("passkey_not_found", 404, "The passkey was not found.")
	CodePasskeyRequired                   = def("passkey_required", 403, "Sign in with your passkey.")
	CodePasskeyUserVerificationRequired   = def("passkey_user_verification_required", 401, "The passkey must verify the user.")
	CodePasswordChangeFailed              = def("password_change_failed", 400, "The password could not be changed.")
	CodePasswordContainsIdentifier        = defParam("password_contains_identifier", 400, "password", "The password must not contain your username or email.")
	CodePasswordRequirementsUnmet         = defParam("password_requirements_unmet", 400, "password", "The password does not meet the character requirements.")
	CodePasswordResetRequired             = def("password_reset_required", 401, "A password reset is required before you can sign in.")
	CodePasswordTooCommon                 = defParam("password_too_common", 400, "password", "The password is too common.")
	CodePasswordTooLong                   = defParam("password_too_long", 400, "password", "The password is too long.")
	CodePasswordTooShort                  = defParam("password_too_short", 400, "password", "The password is too short.")
	CodePasswordlessDisabled              = def("passwordless_disabled", 403, "Passwordless login is disabled.")
	CodePermissionNotGranted              = def("permission_not_granted", 403, "The token claims a permission it was not granted.")
	CodePhoneAlreadyVerified              = def("phone_already_verified", 409, "The phone number is already verified.")
	CodePhoneInUse                        = def("phone_in_use", 400, "That phone number is already in use.")
	CodePhoneNumberMustBeE164             = def("phone_number_must_be_e164", 400, "The phone number must be in E.164 format.")
	CodePhoneNumberRequired               = def("phone_number_required", 400, "A phone number is required.")
	CodeProviderAlreadyLinked             = def("provider_already_linked", 409, "That provider identity is already linked to another account.")
	CodeProviderChangeRequiresUnlink      = def("provider_change_requires_unlink", 409, "Unlink the current provider account before linking another.")
	CodeProviderError                     = def("provider_error", 400, "The provider returned an error.")
	CodeProviderNotLinked                 = def("provider_not_linked", 400, "That provider is not linked.")
	CodeProviderUnavailable               = def("provider_unavailable", 503, "The identity provider is temporarily unavailable.")
	CodeRateLimited                       = def("rate_limited", 429, "Too many requests. Please try again later.")
	CodeRegistrationDisabled              = def("registration_disabled", 403, "Registration is currently disabled.")
	CodeRemoteApplicationAccessHasSubject = def("remote_application_access_has_subject", 401, "A remote-application token must not carry a subject.")
	CodeRemoteApplicationIssuerConflict   = def("remote_application_issuer_conflict", 409, "That issuer already belongs to another remote application.")
	CodeRemoteApplicationNotFound         = def("remote_application_not_found", 404, "The remote application was not found.")
	CodeRenameRateLimited                 = def("rename_rate_limited", 429, "Too many renames. Please try again later.")
	CodeRenamesDisabled                   = def("renames_disabled", 403, "Renames are disabled.")
	CodeReservedIssuer                    = def("reserved_issuer", 400, "That issuer is reserved.")
	CodeRoleAssignmentEscalation          = def("role_assignment_escalation", 403, "That role confers authority you do not hold.")
	CodeRoleNotAssignable                 = def("role_not_assignable", 400, "The role cannot be assigned in this group.")
	CodeSenderProofRequired               = def("sender_proof_required", 401, "The token requires sender proof.")
	CodeServiceJWTLifetimeExceeded        = def("service_jwt_lifetime_exceeded", 401, "The service token lifetime is too long.")
	CodeSessionRevoked                    = def("session_revoked", 401, "This session has ended. Please sign in again.")
	CodeSMSDeliveryFailed                 = def("sms_delivery_failed", 502, "The SMS could not be delivered.")
	CodeSMSUnavailable                    = def("sms_unavailable", 503, "SMS is unavailable.")
	CodeStepUpRequired                    = def("step_up_required", 403, "Additional verification is required to continue.")
	CodeTokenExpired                      = def("token_expired", 401, "The authentication token has expired.")
	CodeTokenNotYetValid                  = def("token_not_yet_valid", 401, "The token is not yet valid.")
	CodeTTLExceedsDelegateCertificate     = def("ttl_exceeds_delegate_certificate", 400, "The TTL exceeds the delegate certificate.")
	CodeUnauthenticated                   = def("unauthenticated", 401, "Authentication is required.")
	CodeUnknownGroupPersona               = def("unknown_group_persona", 400, "Unknown group persona.")
	CodeUnknownKID                        = def("unknown_kid", 401, "The token names an unknown key.")
	CodeUnknownProvider                   = def("unknown_provider", 400, "Unknown provider.")
	CodeUnsupportedTokenTyp               = def("unsupported_token_typ", 401, "The token type is not supported.")
	CodeUserBanned                        = def("user_banned", 401, "This account is banned.")
	CodeUserNotFound                      = def("user_not_found", 404, "User not found.")
	CodeUserReferenced                    = def("user_referenced", 409, "The user is still referenced.")
	CodeUsernameCannotContainAt           = defParam("username_cannot_contain_at", 400, "username", "The username cannot contain @.")
	CodeUsernameCannotStartWithPlus       = defParam("username_cannot_start_with_plus", 400, "username", "The username cannot start with +.")
	CodeUsernameInUse                     = defParam("username_in_use", 400, "username", "That username is already in use.")
	CodeUsernameInvalidCharacters         = defParam("username_invalid_characters", 400, "username", "The username contains invalid characters.")
	CodeUsernameMustStartWithLetter       = defParam("username_must_start_with_letter", 400, "username", "The username must start with a letter.")
	CodeUsernameNotAllowed                = defParam("username_not_allowed", 400, "username", "That username is not allowed.")
	CodeUsernameTooLong                   = defParam("username_too_long", 400, "username", "The username is too long.")
	CodeUsernameTooShort                  = defParam("username_too_short", 400, "username", "The username is too short.")
	CodeVerificationRequired              = def("verification_required", 403, "Verify your contact details to continue.")
	CodeWalletAlreadyLinked               = def("wallet_already_linked", 409, "That wallet is already linked to another account.")
	CodeWalletChangeRequiresUnlink        = def("wallet_change_requires_unlink", 409, "Unlink your current wallet before connecting another.")
)
View Source
var (
	ErrAccountExistsLinkRequired       = E(CodeAccountExistsLinkRequired)
	ErrAddressMismatch                 = E(CodeAddressMismatch)
	ErrAvatarURLInvalid                = E(CodeAvatarURLInvalid)
	ErrBootstrapDatabaseNotEmpty       = E(CodeBootstrapDatabaseNotEmpty)
	ErrChallengeExpired                = E(CodeChallengeExpired)
	ErrChallengeMismatch               = E(CodeChallengeMismatch)
	ErrChallengeNotFound               = E(CodeChallengeNotFound)
	ErrCodeExpired                     = E(CodeCodeExpired)
	ErrEmailAlreadyVerified            = E(CodeEmailAlreadyVerified)
	ErrEmailDeliveryFailed             = E(CodeEmailDeliveryFailed)
	ErrEmailUnavailable                = E(CodeEmailUnavailable)
	ErrEmailVerificationSendFailed     = Internal("email_verification_failed", nil)
	ErrEntitlementFilterUnavailable    = E(CodeEntitlementFilterUnavailable)
	ErrInvalidBootstrapManifest        = E(CodeInvalidBootstrapManifest)
	ErrInvalidCode                     = E(CodeInvalidCode)
	ErrInvalidCredentials              = E(CodeInvalidCredentials)
	ErrInvalidDomain                   = E(CodeInvalidDomain)
	ErrInvalidExpiry                   = E(CodeInvalidExpiry)
	ErrInvalidIdentifier               = E(CodeInvalidIdentifier)
	ErrInvalidInvite                   = E(CodeInvalidInvite)
	ErrInvalidSignature                = E(CodeInvalidSignature)
	ErrInvalidTimestamp                = E(CodeInvalidTimestamp)
	ErrInvalidTwoFAMethod              = E(CodeInvalidTwoFAMethod)
	ErrInvitationExpired               = E(CodeInvitationExpired)
	ErrInvitationRevoked               = E(CodeInvitationRevoked)
	ErrMissingName                     = E(CodeMissingName)
	ErrNameAdmissionRefused            = E(CodeNameAdmissionRefused)
	ErrPasskeyCloneDetected            = E(CodePasskeyCloneDetected)
	ErrPasskeyNotFound                 = E(CodePasskeyNotFound)
	ErrPasskeyRequired                 = E(CodePasskeyRequired)
	ErrPasskeyUserVerificationRequired = E(CodePasskeyUserVerificationRequired)
	ErrPasswordResetRequired           = E(CodePasswordResetRequired)
	ErrPasswordlessDisabled            = E(CodePasswordlessDisabled)
	ErrPhoneAlreadyVerified            = E(CodePhoneAlreadyVerified)
	ErrPhoneNumberMustBeE164           = E(CodePhoneNumberMustBeE164)
	ErrPhoneNumberRequired             = E(CodePhoneNumberRequired)
	ErrPhoneVerificationSendFailed     = Internal("phone_verification_failed", nil)
	ErrProviderAlreadyLinked           = E(CodeProviderAlreadyLinked)
	ErrProviderChangeRequiresUnlink    = E(CodeProviderChangeRequiresUnlink)
	ErrRegistrationDisabled            = E(CodeRegistrationDisabled)
	ErrSMSDeliveryFailed               = E(CodeSMSDeliveryFailed)
	ErrSMSUnavailable                  = E(CodeSMSUnavailable)
	ErrStepUpRequired                  = E(CodeStepUpRequired)
	ErrTwoFAEnableFailed               = Internal("enable_2fa_failed", nil)
	ErrTwoFAFactorExists               = E(CodeTwoFAFactorExists)
	ErrTwoFAMethodUnavailable          = E(CodeTwoFAMethodUnavailable)
	ErrTwoFASetupCodeSendFailed        = Internal("send_code_failed", nil)
	ErrUserBanned                      = E(CodeUserBanned)
	ErrUserReferenced                  = E(CodeUserReferenced)
	ErrWalletAlreadyLinked             = E(CodeWalletAlreadyLinked)
	ErrWalletChangeRequiresUnlink      = E(CodeWalletChangeRequiresUnlink)
)

Sentinels the engine and the HTTP layer match with errors.Is. Host-facing sentinels live in iam.

Functions

func Message added in v0.147.0

func Message(code Code) string

Message is the catalog message of code.

func Status added in v0.147.0

func Status(code Code) int

Status is the catalog status of code (500 when uncatalogued).

Types

type Code

type Code string

Code is a stable, snake_case wire error code.

func CodeOf added in v0.147.0

func CodeOf(err error) Code

CodeOf is the catalog code of the *Error in err's chain ("" when none).

func Codes

func Codes() []Code

Codes lists every wire code, sorted.

func (Code) String

func (c Code) String() string

type Error

type Error struct {
	// contains filtered or unexported fields
}

Error is the one error value. Its status is always the catalog's for its code: no call site can override it. An uncatalogued code, and every Internal failure, answers 500 internal_error on the wire.

func As

func As(err error) *Error

As returns the *Error in err's chain, or nil.

func E

func E(code Code, opts ...Option) *Error

E builds an Error for a catalogued code.

func Internal added in v0.147.0

func Internal(op string, cause error) *Error

Internal is a server failure: internal_error on the wire, op and cause in the log.

func Recode

func Recode(err error, code Code, opts ...Option) *Error

Recode re-tags err with a route-specific code, keeping err as the cause and carrying an inner Error's param and metadata forward.

func Wire added in v0.147.0

func Wire(err error) *Error

Wire is what the envelope carries for err: anything that is not an *Error is a 500 internal_error.

func (*Error) Code

func (e *Error) Code() string

Code is the wire code: the catalog code, or internal_error for a 500.

func (*Error) Error

func (e *Error) Error() string

func (*Error) Is

func (e *Error) Is(target error) bool

Is matches any *Error with the same code (and, for Internal failures, the same op), so a sentinel, a fresh E() and a wrapped copy are one identity.

func (*Error) Message

func (e *Error) Message() string

Message is the catalog's human-readable message for the wire code.

func (*Error) Metadata added in v0.147.0

func (e *Error) Metadata() map[string]any

Metadata is a copy of the machine-readable context (nil when empty or for a server failure).

func (*Error) Param

func (e *Error) Param() string

Param names the offending request field: the site's, else the catalog's. A server failure carries none.

func (*Error) Status

func (e *Error) Status() int

Status is the catalog's HTTP status for the code (500 when uncatalogued).

func (*Error) Unwrap

func (e *Error) Unwrap() error

type Option

type Option func(*Error)

Option customises an E() value.

func WithCause

func WithCause(cause error) Option

func WithMeta

func WithMeta(key string, value any) Option

func WithMetadata

func WithMetadata(m map[string]any) Option

WithMetadata merges a whole map into the metadata.

func WithParam

func WithParam(param string) Option

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL