errors

package module
v1.8.1 Latest Latest
Warning

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

 Go to latest Published: Jul 5, 2026 License: MIT Imports: 2 Imported by: 9

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrNotImplemented indicates that a given feature is not implemented yet.
	ErrNotImplemented error = New("feature not implemented yet").
						WithCode("FEATURE_NOT_IMPLEMENTED").
						WithKind(KindInternal)

	// ErrMock is a fake mocked that should be used in test scenarios.
	ErrMock error = New("mocked error").
			WithCode("MOCKED_ERROR").
			WithKind(KindInternal)

	// ErrResourceNotFound indicates that a desired resource was not found.
	ErrResourceNotFound error = New("resource not found").
						WithCode("RESOURCE_NOT_FOUND").
						WithKind(KindNotFound)

	// ErrRequestUnauthenticated indicates that the request made to an API has missing or invalid credentials.
	ErrRequestUnauthenticated = New("unauthenticated request").
								WithCode("ERR_UNAUTHENTICATED").
								WithKind(KindUnauthenticated)

	// ErrRequestUnauthorized indicates that the request made to an API has missing or invalid credentials.
	ErrRequestUnauthorized = New("unauthorized request").
							WithCode("ERR_UNAUTHORIZED").
							WithKind(KindUnauthorized)

	// ErrRequestError occurs when there is any error on requests to external systems.
	ErrRequestError = New("request to external system failed").
					WithCode("ERR_REQUEST_TO_EXTERNAL_SYSTEM_FAILED").
					WithKind(KindInternal).
					Retryable()

	// ErrUnexpectedResponseStatus occurs when a request to an external system returns an unexpected status code.
	ErrUnexpectedResponseStatus = New("unexpected status response from external system").
								WithCode("ERR_UNEXPECTED_RESPONSE_STATUS").
								WithKind(KindInternal).
								Retryable()

	// ErrCastResponsePayload indicates an issue during response payload casting.
	ErrCastResponsePayload = New("could not cast response data").
							WithCode("ERR_CAST_RESPONSE_PAYLOAD").
							WithKind(KindInternal)

	// ErrInvalidInput occurs when a given input is invalid.
	ErrInvalidInput = New("invalid input").
					WithCode("ERR_INVALID_INPUT").
					WithKind(KindInvalidInput)

	// ErrInvalidAccountID occurs when a given account ID is invalid.
	ErrInvalidAccountID = New("invalid account ID").
						WithCode("ERR_INVALID_ACCOUNT_ID").
						WithKind(KindInvalidInput)

	// ErrFetchFeatureFlag occurs when a request made to a Feature Flag service fails.
	ErrFetchFeatureFlag = New("could not fetch feature flag").
						WithCode("ERR_FETCH_FEATURE_FLAG").
						WithKind(KindInternal).
						Retryable()

	// ErrContextCanceled indicates that an operation was canceled, typically by a context cancellation.
	ErrContextCanceled = New("operation canceled").
						WithCode("ERR_CONTEXT_CANCELED").
						WithKind(KindCanceled).
						Retryable()
)

Functions

func As added in v1.5.0 

func As(err error, target any) bool

As finds the first error in err's tree that matches target, and if one is found, sets target to that error value and returns true. Otherwise, it returns false.

The tree consists of err itself, followed by the errors obtained by repeatedly calling its Unwrap() error or Unwrap() []error method. When err wraps multiple errors, As examines err followed by a depth-first traversal of its children.

An error matches target if the error's concrete value is assignable to the value pointed to by target, or if the error has a method As(interface{}) bool such that As(target) returns true. In the latter case, the As method is responsible for setting target.

An error type might provide an As method so it can be treated as if it were a different error type.

As panics if target is not a non-nil pointer to either a type that implements error, or to any interface type.

func Is 

func Is(err, target error) bool

Is reports whether any error in err's tree matches target.

The tree consists of err itself, followed by the errors obtained by repeatedly calling its Unwrap() error or Unwrap() []error method. When err wraps multiple errors, Is examines err followed by a depth-first traversal of its children.

An error is considered to match a target if it is equal to that target or if it implements a method Is(error) bool such that Is(target) returns true.

An error type might provide an Is method so it can be treated as equivalent to an existing error. For example, if MyError defines 

func (m MyError) Is(target error) bool { return target == fs.ErrExist }

then Is(MyError{}, fs.ErrExist) returns true. See syscall.Errno.Is for an example in the standard library. An Is method should only shallowly compare err and the target and not call Unwrap on either.

func IsRetryable added in v1.5.0 

func IsRetryable(err error) bool

IsRetryable reports whether any error in err's tree is retryable.

The tree consists of err itself, followed by the errors obtained by repeatedly calling its Unwrap() error or Unwrap() []error method. When err wraps multiple errors, Is examines err followed by a depth-first traversal of its children.

func Reasons added in v1.7.0 

func Reasons(err error) []string

Reasons returns all the reasons that led to the creation of the given error.

func SafeReasons added in v1.7.0 

func SafeReasons(err error) []string

SafeReasons returns all the reasons that led to the creation of the given error. It does not exposes non CustomErrors as reasons, to prevent exposing internal details.

func Unwrap added in v1.5.0 

func Unwrap(err error) []error

Unwrap retrieves all the errors that forms the baseline for the given one. It only works in the surface of the error. In other words, it does not evaluates all the err's tree, just its first level.

func Wrap added in v1.5.0 

func Wrap(err error, msg string, args ...any) error

Wrap adds more contextual information into the given error. The new information is handled as a new error which wraps the given error properly.

Types

type AttributeSet added in v1.7.0 

type AttributeSet map[string]string

AttributeSet is a map of string key-value pairs that can be used to add additional information to an error.

func Attributes added in v1.7.0 

func Attributes(err error) AttributeSet

Attributes retrieves all the attributes that defined in the given error.

func (AttributeSet) Merge added in v1.7.0 

func (s AttributeSet) Merge(other AttributeSet)

Merge merges the given AttributeSet into the current one.

type CodeType 

type CodeType string
const CodeUnknown CodeType = "UNKNOWN"

func Code 

func Code(err error) CodeType

Code retrieves the first non unknown Code in err's tree. CodeUnknown indicates that no Code was set or no CustomError was found in the tree.

The tree consists of err itself, followed by the errors obtained by repeatedly calling its Unwrap() error or Unwrap() []error method. When err wraps multiple errors, Is examines err followed by a depth-first traversal of its children.

type CustomError 

type CustomError interface {
	error

	// WithKind return a copy of the CustomError with the given KindType filled.
	WithKind(kind KindType) CustomError

	// WithCode return a copy of the CustomError with the given CodeType filled.
	WithCode(code CodeType) CustomError

	// WithCause return a copy of the CustomError with the given Cause attached as the
	// last internal error of this CustomError.
	WithCause(cause error) CustomError

	// WithAttribute returns a copy of the CustomError with the given Attribute filled.
	WithAttribute(key, value string) CustomError

	// Retryable returns a copy of the CustomError tagged as retryable.
	Retryable() CustomError
}

CustomError is an error that encodes useful information about a given error.

Kind: Gives semantics for the error. It is expected to be interpreted by transport layers; Code: Defines what the Error actually is, by an unique alias; Retryable: Indicates if the given error may be fixed with a retry execution.

It is designed to work well within a Go Error Tree.

func New 

func New(msg string, args ...any) CustomError

New returns a new instance of CustomError with the given message. It uses KindUnknown, CodeUnknown and 'false' by default for Kind, Code and Retryable attributes, respectively.

type KindType 

type KindType string
const (
	KindUnknown            KindType = "UNKNOWN"
	KindConflict           KindType = "CONFLICT"
	KindInternal           KindType = "INTERNAL"
	KindInvalidInput       KindType = "INVALID_INPUT"
	KindNotFound           KindType = "NOT_FOUND"
	KindUnauthenticated    KindType = "UNAUTHENTICATED"
	KindUnauthorized       KindType = "UNAUTHORIZED"
	KindUnprocessable      KindType = "UNPROCESSABLE"
	KindResourceExhausted  KindType = "RESOURCE_EXHAUSTED"
	KindServiceUnavailable KindType = "SERVICE_UNAVAILABLE"
	KindCritical           KindType = "CRITICAL"
	KindFatal              KindType = "FATAL"
	KindCanceled           KindType = "CANCELED"
	KindWarn               KindType = "WARN"
)

func Kind 

func Kind(err error) KindType

Kind retrieves the first non unknown Kind in err's tree. KindUnknown indicates that no Kind was set or no CustomError was found in the tree.

The tree consists of err itself, followed by the errors obtained by repeatedly calling its Unwrap() error or Unwrap() []error method. When err wraps multiple errors, Is examines err followed by a depth-first traversal of its children.

type SeverityType added in v1.7.0 

type SeverityType int
const (
	SeverityWarn SeverityType = iota

	// SeverityError indicates a regular error.
	SeverityError

	// SeverityCritical indicates a critical error.
	// Typically, this kind of error is not expected to happen and may require immediate attention.
	SeverityCritical

	// SeverityFatal indicates a fatal error.
	// Typically, this kind of error is not expected to happen and will cause the application to crash.
	SeverityFatal
)

func Severity added in v1.7.0 

func Severity(err error) SeverityType

Severity retrieves the relevant SeverityType for the given error based on its Kind.

func (SeverityType) String added in v1.7.0 

func (s SeverityType) String() string

String returns the string representation of the SeverityType.

Source Files

View all Source files

Directories

Path Synopsis

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.