errs

package
v1.0.47 Latest Latest
Warning

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

 Go to latest Published: Jun 3, 2026 License: MIT Imports: 3 Imported by: 0

Documentation

Overview

Package errs is the public error-contract surface for lark-cli.

It defines a closed taxonomy (9 Categories) and a small set of typed errors that embed Problem — an RFC 7807-aligned shared shape. External consumers (AI agents, shell scripts, integrating SDKs) read structured fields instead of regex-parsing free-string error messages.

The Problem shape

Every typed error embeds Problem so the JSON wire shape (`type`, `subtype`, `code`, `message`, `hint`, `log_id`, `retryable`) is uniform across categories. Typed extensions (PermissionError.MissingScopes, SecurityPolicyError.ChallengeURL, etc.) appear at the top level of the envelope alongside the shared fields, not nested under a `detail` key.

Working with typed errors

Use ProblemOf to read shared fields polymorphically: 

if p, ok := errs.ProblemOf(err); ok {
    log.Printf("category=%s subtype=%s retryable=%t", p.Category, p.Subtype, p.Retryable)
}

Use the IsXxx predicates or stdlib errors.As to branch on concrete type: 

if errs.IsPermission(err) {
    var pe *errs.PermissionError
    _ = errors.As(err, &pe)
    fmt.Println("missing scopes:", pe.MissingScopes)
}

Use WrapInternal at boundaries to lift any non-typed error to *InternalError; typed errors pass through unchanged.

Index

Constants

View Source 
const (
	RiskRead          = "read"
	RiskWrite         = "write"
	RiskHighRiskWrite = "high-risk-write"
	RiskUnknown       = "unknown"
)

Risk classifies the impact of a confirmation-required operation. Every ConfirmationRequiredError MUST populate Risk; callers without a known risk level use RiskUnknown so the envelope is never wire-invalid.

Variables

This section is empty.

Functions

func IsAPI 

func IsAPI(err error) bool

IsAPI reports whether err is an *APIError.

func IsAuthentication 

func IsAuthentication(err error) bool

IsAuthentication reports whether err is an *AuthenticationError.

func IsConfig 

func IsConfig(err error) bool

IsConfig reports whether err is a *ConfigError.

func IsConfirmationRequired 

func IsConfirmationRequired(err error) bool

IsConfirmationRequired reports whether err is a *ConfirmationRequiredError.

func IsContentSafety 

func IsContentSafety(err error) bool

IsContentSafety reports whether err is a *ContentSafetyError.

func IsInternal 

func IsInternal(err error) bool

IsInternal reports whether err is an *InternalError.

func IsNetwork 

func IsNetwork(err error) bool

IsNetwork reports whether err is a *NetworkError.

func IsPermission 

func IsPermission(err error) bool

IsPermission reports whether err is a *PermissionError.

func IsRetryable 

func IsRetryable(err error) bool

IsRetryable reads Problem.Retryable; non-typed errors are non-retryable by default.

func IsSecurityPolicy 

func IsSecurityPolicy(err error) bool

IsSecurityPolicy reports whether err is a *SecurityPolicyError.

func IsTyped added in v1.0.45 

func IsTyped(err error) bool

IsTyped reports whether err is or wraps any of the typed *errs.* errors in this package (i.e. implements the TypedError interface). Used by call sites that need to pass already-classified errors through unchanged instead of blanket-rewrapping them as a different category.

func IsValidation 

func IsValidation(err error) bool

IsValidation reports whether err is a *ValidationError.

func UnwrapTypedError 

func UnwrapTypedError(err error) (error, bool)

UnwrapTypedError walks the wrap chain and returns the first error that embeds Problem (i.e. any typed error in this package). Returns the typed error itself (as error) so callers — notably JSON marshaling — see the concrete value's own struct tags rather than an opaque wrapper.

func WrapInternal 

func WrapInternal(err error) error

WrapInternal wraps a non-typed error into *InternalError. Typed errors (anything implementing problemCarrier) pass through unchanged. Component is metric-only and derived by the dispatcher, so it is not a parameter here.

Types

type APIError 

type APIError struct {
	Problem
	Cause error `json:"-"`
}

APIError is the typed error for CategoryAPI (catch-all for classified Lark API business errors). Cause preserves an optional wrapped sentinel for errors.Is / errors.Unwrap; it is intentionally not serialized.

func NewAPIError added in v1.0.45 

func NewAPIError(subtype Subtype, format string, args ...any) *APIError

func (*APIError) Error added in v1.0.45 

func (e *APIError) Error() string

Error is nil-receiver safe; see ValidationError.Error.

func (*APIError) Unwrap added in v1.0.45 

func (e *APIError) Unwrap() error

Unwrap is nil-receiver safe; see ValidationError.Unwrap.

func (*APIError) WithCause added in v1.0.45 

func (e *APIError) WithCause(cause error) *APIError

func (*APIError) WithCode added in v1.0.45 

func (e *APIError) WithCode(code int) *APIError

func (*APIError) WithHint added in v1.0.45 

func (e *APIError) WithHint(format string, args ...any) *APIError

func (*APIError) WithLogID added in v1.0.45 

func (e *APIError) WithLogID(logID string) *APIError

func (*APIError) WithRetryable added in v1.0.45 

func (e *APIError) WithRetryable() *APIError

type AuthenticationError 

type AuthenticationError struct {
	Problem
	UserOpenID string `json:"user_open_id,omitempty"`
	Cause      error  `json:"-"`
}

AuthenticationError is the typed error for CategoryAuthentication. Cause preserves an optional wrapped sentinel for errors.Is / errors.Unwrap; it is intentionally not serialized.

func NewAuthenticationError added in v1.0.45 

func NewAuthenticationError(subtype Subtype, format string, args ...any) *AuthenticationError

func (*AuthenticationError) Error added in v1.0.45 

func (e *AuthenticationError) Error() string

Error is nil-receiver safe; see ValidationError.Error.

func (*AuthenticationError) Unwrap 

func (e *AuthenticationError) Unwrap() error

Unwrap is nil-receiver safe; see ValidationError.Unwrap.

func (*AuthenticationError) WithCause added in v1.0.45 

func (e *AuthenticationError) WithCause(cause error) *AuthenticationError

func (*AuthenticationError) WithCode added in v1.0.45 

func (e *AuthenticationError) WithCode(code int) *AuthenticationError

func (*AuthenticationError) WithHint added in v1.0.45 

func (e *AuthenticationError) WithHint(format string, args ...any) *AuthenticationError

func (*AuthenticationError) WithLogID added in v1.0.45 

func (e *AuthenticationError) WithLogID(logID string) *AuthenticationError

func (*AuthenticationError) WithRetryable added in v1.0.45 

func (e *AuthenticationError) WithRetryable() *AuthenticationError

func (*AuthenticationError) WithUserOpenID added in v1.0.45 

func (e *AuthenticationError) WithUserOpenID(id string) *AuthenticationError

type Category 

type Category string

Category is the top-level taxonomy axis. Wire JSON: "type". 

const (
	CategoryValidation     Category = "validation"
	CategoryAuthentication Category = "authentication"
	CategoryAuthorization  Category = "authorization"
	CategoryConfig         Category = "config"
	CategoryNetwork        Category = "network"
	CategoryAPI            Category = "api"
	CategoryPolicy         Category = "policy"
	CategoryInternal       Category = "internal"
	CategoryConfirmation   Category = "confirmation"
)

func CategoryOf 

func CategoryOf(err error) Category

CategoryOf returns the error's Category for metrics/logging/dispatch routing. Falls back to CategoryInternal for non-typed errors.

type ConfigError 

type ConfigError struct {
	Problem
	Field string `json:"field,omitempty"`
	Cause error  `json:"-"`
}

ConfigError is the typed error for CategoryConfig. Cause preserves an optional wrapped sentinel for errors.Is / errors.Unwrap; it is intentionally not serialized.

func NewConfigError added in v1.0.45 

func NewConfigError(subtype Subtype, format string, args ...any) *ConfigError

func (*ConfigError) Error added in v1.0.45 

func (e *ConfigError) Error() string

Error is nil-receiver safe; see ValidationError.Error.

func (*ConfigError) Unwrap 

func (e *ConfigError) Unwrap() error

Unwrap is nil-receiver safe; see ValidationError.Unwrap.

func (*ConfigError) WithCause added in v1.0.45 

func (e *ConfigError) WithCause(cause error) *ConfigError

func (*ConfigError) WithCode added in v1.0.45 

func (e *ConfigError) WithCode(code int) *ConfigError

func (*ConfigError) WithField added in v1.0.45 

func (e *ConfigError) WithField(field string) *ConfigError

func (*ConfigError) WithHint added in v1.0.45 

func (e *ConfigError) WithHint(format string, args ...any) *ConfigError

func (*ConfigError) WithLogID added in v1.0.45 

func (e *ConfigError) WithLogID(logID string) *ConfigError

func (*ConfigError) WithRetryable added in v1.0.45 

func (e *ConfigError) WithRetryable() *ConfigError

type ConfirmationRequiredError 

type ConfirmationRequiredError struct {
	Problem
	Risk   string `json:"risk"`
	Action string `json:"action"`
	Cause  error  `json:"-"`
}

ConfirmationRequiredError is the typed error for CategoryConfirmation. Risk is one of: "read" | "write" | "high-risk-write" | "unknown". Cause preserves an optional wrapped sentinel for errors.Is / errors.Unwrap; it is intentionally not serialized.

func NewConfirmationRequiredError added in v1.0.45 

func NewConfirmationRequiredError(risk, action, format string, args ...any) *ConfirmationRequiredError

NewConfirmationRequiredError constructs a *ConfirmationRequiredError. Risk + Action are wire-required (non-omitempty). Empty inputs are normalized at the constructor boundary so callers cannot build a wire-invalid envelope: risk falls back to RiskUnknown, action to "unknown". risk is one of: "read" | "write" | "high-risk-write".

func (*ConfirmationRequiredError) Error added in v1.0.45 

func (e *ConfirmationRequiredError) Error() string

Error is nil-receiver safe; see ValidationError.Error.

func (*ConfirmationRequiredError) Unwrap added in v1.0.45 

func (e *ConfirmationRequiredError) Unwrap() error

Unwrap is nil-receiver safe; see ValidationError.Unwrap.

func (*ConfirmationRequiredError) WithCause added in v1.0.45 

func (e *ConfirmationRequiredError) WithCause(cause error) *ConfirmationRequiredError

func (*ConfirmationRequiredError) WithCode added in v1.0.45 

func (e *ConfirmationRequiredError) WithCode(code int) *ConfirmationRequiredError

func (*ConfirmationRequiredError) WithHint added in v1.0.45 

func (e *ConfirmationRequiredError) WithHint(format string, args ...any) *ConfirmationRequiredError

func (*ConfirmationRequiredError) WithLogID added in v1.0.45 

func (e *ConfirmationRequiredError) WithLogID(logID string) *ConfirmationRequiredError

type ContentSafetyError 

type ContentSafetyError struct {
	Problem
	Rules []string `json:"rules,omitempty"`
	Cause error    `json:"-"`
}

ContentSafetyError is the typed error for CategoryPolicy content-safety subtypes. Cause preserves an optional wrapped sentinel for errors.Is / errors.Unwrap; it is intentionally not serialized.

func NewContentSafetyError added in v1.0.45 

func NewContentSafetyError(subtype Subtype, format string, args ...any) *ContentSafetyError

func (*ContentSafetyError) Error added in v1.0.45 

func (e *ContentSafetyError) Error() string

Error is nil-receiver safe; see ValidationError.Error.

func (*ContentSafetyError) Unwrap added in v1.0.45 

func (e *ContentSafetyError) Unwrap() error

Unwrap is nil-receiver safe; see ValidationError.Unwrap.

func (*ContentSafetyError) WithCause added in v1.0.45 

func (e *ContentSafetyError) WithCause(cause error) *ContentSafetyError

func (*ContentSafetyError) WithCode added in v1.0.45 

func (e *ContentSafetyError) WithCode(code int) *ContentSafetyError

func (*ContentSafetyError) WithHint added in v1.0.45 

func (e *ContentSafetyError) WithHint(format string, args ...any) *ContentSafetyError

func (*ContentSafetyError) WithLogID added in v1.0.45 

func (e *ContentSafetyError) WithLogID(logID string) *ContentSafetyError

func (*ContentSafetyError) WithRetryable added in v1.0.45 

func (e *ContentSafetyError) WithRetryable() *ContentSafetyError

func (*ContentSafetyError) WithRules added in v1.0.45 

func (e *ContentSafetyError) WithRules(rules ...string) *ContentSafetyError

type InternalError 

type InternalError struct {
	Problem
	Cause error `json:"-"`
}

InternalError is the typed error for CategoryInternal. Cause is preserved for logging but not emitted on the wire.

func NewInternalError added in v1.0.45 

func NewInternalError(subtype Subtype, format string, args ...any) *InternalError

func (*InternalError) Error added in v1.0.45 

func (e *InternalError) Error() string

Error is nil-receiver safe; see ValidationError.Error.

func (*InternalError) Unwrap 

func (e *InternalError) Unwrap() error

Unwrap is nil-receiver safe; see ValidationError.Unwrap.

func (*InternalError) WithCause added in v1.0.45 

func (e *InternalError) WithCause(cause error) *InternalError

func (*InternalError) WithCode added in v1.0.45 

func (e *InternalError) WithCode(code int) *InternalError

func (*InternalError) WithHint added in v1.0.45 

func (e *InternalError) WithHint(format string, args ...any) *InternalError

func (*InternalError) WithLogID added in v1.0.45 

func (e *InternalError) WithLogID(logID string) *InternalError

func (*InternalError) WithRetryable added in v1.0.45 

func (e *InternalError) WithRetryable() *InternalError

type InvalidParam added in v1.0.47 

type InvalidParam struct {
	Name   string `json:"name"`
	Reason string `json:"reason"`
}

InvalidParam is one structured validation diagnostic: the parameter that failed (Name) and why (Reason). It mirrors an RFC 7807 "invalid-params" item (RFC 7807 §3.1 extension members).

The wire key on ValidationError is "params" rather than "invalid_params" because the enclosing envelope already carries type:"validation", so the "invalid" qualifier would be redundant on the wire. The Go type keeps the InvalidParam prefix because, at package level, the name must self-describe.

type NetworkError 

type NetworkError struct {
	Problem
	Cause error `json:"-"`
}

NetworkError is the typed error for CategoryNetwork. The Subtype carries the failure taxonomy: timeout / tls / dns / server_error, with transport as the fallback. Cause preserves an optional wrapped sentinel for errors.Is / errors.Unwrap; it is intentionally not serialized.

func NewNetworkError added in v1.0.45 

func NewNetworkError(subtype Subtype, format string, args ...any) *NetworkError

func (*NetworkError) Error added in v1.0.45 

func (e *NetworkError) Error() string

Error is nil-receiver safe; see ValidationError.Error.

func (*NetworkError) Unwrap 

func (e *NetworkError) Unwrap() error

Unwrap is nil-receiver safe; see ValidationError.Unwrap.

func (*NetworkError) WithCause added in v1.0.45 

func (e *NetworkError) WithCause(cause error) *NetworkError

func (*NetworkError) WithCode added in v1.0.45 

func (e *NetworkError) WithCode(code int) *NetworkError

func (*NetworkError) WithHint added in v1.0.45 

func (e *NetworkError) WithHint(format string, args ...any) *NetworkError

func (*NetworkError) WithLogID added in v1.0.45 

func (e *NetworkError) WithLogID(logID string) *NetworkError

func (*NetworkError) WithRetryable added in v1.0.45 

func (e *NetworkError) WithRetryable() *NetworkError

type PermissionError 

type PermissionError struct {
	Problem
	MissingScopes   []string `json:"missing_scopes,omitempty"`
	RequestedScopes []string `json:"requested_scopes,omitempty"`
	GrantedScopes   []string `json:"granted_scopes,omitempty"`
	Identity        string   `json:"identity,omitempty"`
	ConsoleURL      string   `json:"console_url,omitempty"`
	Cause           error    `json:"-"`
}

PermissionError is the typed error for CategoryAuthorization. Cause preserves an optional wrapped sentinel for errors.Is / errors.Unwrap; it is intentionally not serialized.

func NewPermissionError added in v1.0.45 

func NewPermissionError(subtype Subtype, format string, args ...any) *PermissionError

func (*PermissionError) Error added in v1.0.45 

func (e *PermissionError) Error() string

Error is nil-receiver safe; see ValidationError.Error.

func (*PermissionError) Unwrap added in v1.0.45 

func (e *PermissionError) Unwrap() error

Unwrap is nil-receiver safe; see ValidationError.Unwrap.

func (*PermissionError) WithCause added in v1.0.45 

func (e *PermissionError) WithCause(cause error) *PermissionError

func (*PermissionError) WithCode added in v1.0.45 

func (e *PermissionError) WithCode(code int) *PermissionError

func (*PermissionError) WithConsoleURL added in v1.0.45 

func (e *PermissionError) WithConsoleURL(url string) *PermissionError

func (*PermissionError) WithGrantedScopes added in v1.0.45 

func (e *PermissionError) WithGrantedScopes(scopes ...string) *PermissionError

func (*PermissionError) WithHint added in v1.0.45 

func (e *PermissionError) WithHint(format string, args ...any) *PermissionError

func (*PermissionError) WithIdentity added in v1.0.45 

func (e *PermissionError) WithIdentity(identity string) *PermissionError

func (*PermissionError) WithLogID added in v1.0.45 

func (e *PermissionError) WithLogID(logID string) *PermissionError

func (*PermissionError) WithMissingScopes added in v1.0.45 

func (e *PermissionError) WithMissingScopes(scopes ...string) *PermissionError

func (*PermissionError) WithRequestedScopes added in v1.0.45 

func (e *PermissionError) WithRequestedScopes(scopes ...string) *PermissionError

func (*PermissionError) WithRetryable added in v1.0.45 

func (e *PermissionError) WithRetryable() *PermissionError

type Problem 

type Problem struct {
	Category       Category `json:"type"`
	Subtype        Subtype  `json:"subtype,omitempty"`
	Code           int      `json:"code,omitempty"`
	Message        string   `json:"message"`
	Hint           string   `json:"hint,omitempty"`
	LogID          string   `json:"log_id,omitempty"`
	Troubleshooter string   `json:"troubleshooter,omitempty"`
	Retryable      bool     `json:"retryable,omitempty"`
}

Problem is the RFC 7807-aligned shared shape embedded by every typed error.

Message is REQUIRED. Producers must populate it; an empty Message will make Error() return "" — a known Go footgun for fmt.Errorf("...: %v", err).

Wire-format notes:

  • No Component field. Service / shortcut component is metric-only enrichment derived by the dispatcher from the cobra command path; it never appears on the wire.
  • No DocURL field. PermissionError carries the same intent via its typed ConsoleURL extension; other typed errors do not link out.
  • Troubleshooter is the upstream Lark API's diagnostic URL (resp.error. troubleshooter). Carried universally so any classified error can surface it; populated by errclass.BuildAPIError when the upstream response includes it, otherwise absent.
  • Retryable uses omitempty so only `true` is emitted; consumers treat absence as false.

func ProblemOf 

func ProblemOf(err error) (*Problem, bool)

ProblemOf extracts the embedded Problem via the non-exported problemCarrier interface. This is the supported way to read shared fields without depending on a specific typed error.

A typed error whose embedded *Problem is nil is treated as "not a problem carrier" — returning (nil, true) here would cause CategoryOf / IsRetryable and other downstream readers to dereference nil.

func (*Problem) Error 

func (p *Problem) Error() string

Error satisfies the standard `error` interface. A nil receiver is treated as the empty string so a stray nil *Problem stored in an error interface cannot panic the dispatcher.

func (*Problem) ProblemDetail 

func (p *Problem) ProblemDetail() *Problem

type SecurityPolicyError 

type SecurityPolicyError struct {
	Problem
	ChallengeURL string `json:"challenge_url,omitempty"`
	Cause        error  `json:"-"`
}

SecurityPolicyError is the typed error for CategoryPolicy security-policy subtypes. Subtype is "challenge_required" or "access_denied"; Code is 21000 or 21001.

func NewSecurityPolicyError added in v1.0.45 

func NewSecurityPolicyError(subtype Subtype, format string, args ...any) *SecurityPolicyError

func (*SecurityPolicyError) Error added in v1.0.45 

func (e *SecurityPolicyError) Error() string

Error is nil-receiver safe; see ValidationError.Error.

func (*SecurityPolicyError) Unwrap 

func (e *SecurityPolicyError) Unwrap() error

Unwrap is nil-receiver safe; see ValidationError.Unwrap.

func (*SecurityPolicyError) WithCause added in v1.0.45 

func (e *SecurityPolicyError) WithCause(cause error) *SecurityPolicyError

func (*SecurityPolicyError) WithChallengeURL added in v1.0.45 

func (e *SecurityPolicyError) WithChallengeURL(url string) *SecurityPolicyError

func (*SecurityPolicyError) WithCode added in v1.0.45 

func (e *SecurityPolicyError) WithCode(code int) *SecurityPolicyError

func (*SecurityPolicyError) WithHint added in v1.0.45 

func (e *SecurityPolicyError) WithHint(format string, args ...any) *SecurityPolicyError

func (*SecurityPolicyError) WithLogID added in v1.0.45 

func (e *SecurityPolicyError) WithLogID(logID string) *SecurityPolicyError

func (*SecurityPolicyError) WithRetryable added in v1.0.45 

func (e *SecurityPolicyError) WithRetryable() *SecurityPolicyError

type Subtype 

type Subtype string

Subtype is the second-level taxonomy axis. Wire JSON: "subtype". 

const (
	SubtypeInvalidArgument    Subtype = "invalid_argument"    // user-supplied flag / arg failed validation (gRPC INVALID_ARGUMENT alignment)
	SubtypeFailedPrecondition Subtype = "failed_precondition" // request is valid but the system/resource state is not in the state required to execute; caller must change state (not retry) — e.g. ambiguous remote mapping (gRPC FAILED_PRECONDITION alignment)
)

CategoryValidation subtypes 

const (
	SubtypeTokenMissing        Subtype = "token_missing"         // no token in request (Authorization header absent / no local token cache)
	SubtypeTokenInvalid        Subtype = "token_invalid"         // token present but content/format wrong
	SubtypeTokenExpired        Subtype = "token_expired"         // token explicitly expired
	SubtypeRefreshTokenInvalid Subtype = "refresh_token_invalid" // refresh_token is v1 legacy format, unusable
	SubtypeRefreshTokenExpired Subtype = "refresh_token_expired" // refresh_token expired
	SubtypeRefreshTokenRevoked Subtype = "refresh_token_revoked" // refresh_token revoked (user logout / admin action)
	SubtypeRefreshTokenReused  Subtype = "refresh_token_reused"  // refresh_token already used (single-use rotation triggered)
	SubtypeRefreshServerError  Subtype = "refresh_server_error"  // refresh endpoint transient error (retryable)
)

CategoryAuthentication subtypes 

const (
	SubtypeMissingScope           Subtype = "missing_scope"            // user authorized app but did not grant this scope
	SubtypeUserUnauthorized       Subtype = "user_unauthorized"        // user never authorized the app
	SubtypeAppScopeNotApplied     Subtype = "app_scope_not_applied"    // app did not apply for this scope on the open platform
	SubtypeTokenScopeInsufficient Subtype = "token_scope_insufficient" // token was issued without this scope (RFC 6750 alignment)
	SubtypeAppUnavailable         Subtype = "app_unavailable"          // app status unavailable
	SubtypeAppDisabled            Subtype = "app_disabled"             // app currently disabled in this tenant (was installed/enabled before)
	SubtypePermissionDenied       Subtype = "permission_denied"        // resource-level permission denial (authenticated but lacks rights for this resource, HTTP 403 / gRPC PERMISSION_DENIED alignment)
)

CategoryAuthorization subtypes 

const (
	SubtypeInvalidClient Subtype = "invalid_client" // app_id / app_secret incorrect (RFC 6749 §5.2 alignment)
	SubtypeNotConfigured Subtype = "not_configured" // local config file absent (user has not run `config init`)
	SubtypeInvalidConfig Subtype = "invalid_config" // local config file present but malformed
)

CategoryConfig subtypes 

const (
	SubtypeNetworkTransport Subtype = "transport"    // fallback when no more-specific network subtype matches
	SubtypeNetworkTimeout   Subtype = "timeout"      // dial / read timeout
	SubtypeNetworkTLS       Subtype = "tls"          // TLS handshake / cert failure
	SubtypeNetworkDNS       Subtype = "dns"          // DNS resolution failure
	SubtypeNetworkServer    Subtype = "server_error" // upstream HTTP 5xx
)

CategoryNetwork subtypes 

const (
	SubtypeRateLimit         Subtype = "rate_limit"         // request rate limit exceeded
	SubtypeConflict          Subtype = "conflict"           // resource state conflict (e.g. concurrent modification)
	SubtypeCrossTenant       Subtype = "cross_tenant"       // operation crosses tenant boundary (not supported)
	SubtypeCrossBrand        Subtype = "cross_brand"        // operation crosses brand boundary (feishu vs lark, not supported)
	SubtypeInvalidParameters Subtype = "invalid_parameters" // API-side parameter validation rejected the request
	SubtypeOwnershipMismatch Subtype = "ownership_mismatch" // caller is not the resource owner
	SubtypeNotFound          Subtype = "not_found"          // referenced resource does not exist (HTTP 404 alignment)
	SubtypeServerError       Subtype = "server_error"       // upstream server-side transient error (HTTP 5xx alignment, retryable)
	SubtypeQuotaExceeded     Subtype = "quota_exceeded"     // resource quota / collection size limit reached (assignees, followers, members, etc.)
	SubtypeAlreadyExists     Subtype = "already_exists"     // idempotency violation: resource already exists in target state
)

CategoryAPI subtypes 

const (
	SubtypeChallengeRequired Subtype = "challenge_required" // user must complete browser challenge / MFA
	SubtypeAccessDenied      Subtype = "access_denied"      // policy denies access outright
)

CategoryPolicy subtypes (security-policy envelope shape) 

const (
	SubtypeSDKError        Subtype = "sdk_error"        // lark SDK Do() returned an unexpected error
	SubtypeInvalidResponse Subtype = "invalid_response" // SDK response body not parsable as JSON
	SubtypeFileIO          Subtype = "file_io"          // local file I/O failure (mkdir / write / read)
	SubtypeStorage         Subtype = "storage"          // local persistence failure (e.g. config file save)

)

CategoryInternal subtypes 

const (
	SubtypeConfirmationRequired Subtype = "confirmation_required" // high-risk operation needs explicit --yes
)

CategoryConfirmation subtypes 

const (
	SubtypeUnknown Subtype = "unknown" // catch-all fallback; producers must prefer a specific subtype
)

type TypedError added in v1.0.45 

type TypedError interface {
	error
	ProblemDetail() *Problem
}

TypedError is implemented by all typed errors in this package. It identifies a value as a typed envelope producer to the dispatcher, which uses it to short-circuit promotion when the outer error is already typed (avoiding overwrite of producer-set Subtype/Hint).

type ValidationError 

type ValidationError struct {
	Problem
	Param  string         `json:"param,omitempty"`
	Params []InvalidParam `json:"params,omitempty"`
	Cause  error          `json:"-"`
}

ValidationError is the typed error for CategoryValidation. Cause preserves an optional wrapped sentinel for errors.Is / errors.Unwrap; it is intentionally not serialized.

func NewValidationError added in v1.0.45 

func NewValidationError(subtype Subtype, format string, args ...any) *ValidationError

NewValidationError constructs a *ValidationError with Category locked to CategoryValidation and Message formatted via fmt.Sprintf(format, args...).

func (*ValidationError) Error added in v1.0.45 

func (e *ValidationError) Error() string

Error returns the typed error message. Nil-safe — falls back to "" when the receiver is a typed nil pointer, mirroring the embedded Problem.Error() guard that promote-through-value-embed would otherwise bypass.

func (*ValidationError) Unwrap 

func (e *ValidationError) Unwrap() error

Unwrap exposes the wrapped cause so errors.Unwrap / errors.Is can traverse it. A nil typed-pointer held inside an error interface is treated as "no cause" so callers cannot panic on `errors.Unwrap(err)`.

func (*ValidationError) WithCause added in v1.0.45 

func (e *ValidationError) WithCause(cause error) *ValidationError

func (*ValidationError) WithCode added in v1.0.45 

func (e *ValidationError) WithCode(code int) *ValidationError

func (*ValidationError) WithHint added in v1.0.45 

func (e *ValidationError) WithHint(format string, args ...any) *ValidationError

func (*ValidationError) WithLogID added in v1.0.45 

func (e *ValidationError) WithLogID(logID string) *ValidationError

func (*ValidationError) WithParam added in v1.0.45 

func (e *ValidationError) WithParam(param string) *ValidationError

func (*ValidationError) WithParams added in v1.0.47 

func (e *ValidationError) WithParams(params ...InvalidParam) *ValidationError

func (*ValidationError) WithRetryable added in v1.0.45 

func (e *ValidationError) WithRetryable() *ValidationError

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.