Documentation
¶
Overview ¶
Package errors provides error handling primitives for Go 1.21+.
This is a modern reimplementation of error handling, designed for Go 1.21+. It leverages the standard library's errors package (errors.Is, errors.As, errors.Join, fmt.Errorf with %w) while providing error codes, stack traces, and a registration system for API error responses.
Key features:
- Error codes with HTTP status mapping
- Stack traces for debugging
- Unwrap support for error chain traversal
- Compatible with errors.Is and errors.As
Basic usage:
err := errors.New("something went wrong")
err = errors.Wrap(err, "context added")
err = errors.WithCode(ErrNotFound, "user %d not found", userId)
Checking error codes:
if errors.IsCode(err, ErrNotFound) {
// handle not found
}
Index ¶
- Variables
- func Cause(err error) error
- func Errorf(format string, args ...any) error
- func FormatStack(stack []uintptr) string
- func GetCode(err error) int
- func GetStackTrace(err error) []uintptr
- func HTTPStatus(code int) int
- func IsCode(err error, code int) bool
- func MustRegister(code int, httpStatus int, message string)
- func New(message string) error
- func Register(code int, httpStatus int, message string)
- func WithCode(code int, format string, args ...any) error
- func WithMessage(err error, message string) error
- func WithMessagef(err error, format string, args ...any) error
- func Wrap(err error, message string) error
- func WrapCode(err error, code int, format string, args ...any) error
- func Wrapf(err error, format string, args ...any) error
- type CodedError
- type Coder
- type StackTracer
Constants ¶
This section is empty.
Variables ¶
var ( // Is reports whether any error in err's tree matches target. Is = errors.Is // As finds the first error in err's tree that matches target. As = errors.As // Join returns an error that wraps the given errors. Join = errors.Join // Unwrap returns the result of calling the Unwrap method on err. Unwrap = errors.Unwrap )
Re-export standard library functions for convenience
Functions ¶
func Cause ¶
Cause returns the root cause of the error, traversing the error chain. This is similar to errors.Unwrap but unwraps the entire chain.
func Errorf ¶
Errorf formats according to a format specifier and returns an error with a stack trace.
func FormatStack ¶
FormatStack returns a formatted stack trace as a string.
func GetStackTrace ¶
GetStackTrace extracts stack trace from an error if available.
func HTTPStatus ¶
HTTPStatus returns the HTTP status for an error code. Returns 500 if code is not registered.
func MustRegister ¶
MustRegister is like Register but allows overwriting existing codes.
func Register ¶
Register registers an error code with its HTTP status and message. Panics if the code is 0 or already registered.
func WithMessage ¶
WithMessage annotates err with a message (no stack trace). If err is nil, WithMessage returns nil.
func WithMessagef ¶
WithMessagef annotates err with a formatted message (no stack trace). If err is nil, WithMessagef returns nil.
Types ¶
type CodedError ¶
type CodedError interface {
Code() int
}
CodedError is implemented by errors that have a code.
type Coder ¶
type Coder interface {
// Code returns the error code.
Code() int
// HTTPStatus returns the HTTP status code.
HTTPStatus() int
// Message returns the user-facing message.
Message() string
}
Coder defines an interface for error codes.
func ParseCoder ¶
ParseCoder extracts Coder from an error. Returns unknownCoder if no code is found.
type StackTracer ¶
type StackTracer interface {
StackTrace() []uintptr
}
StackTracer is implemented by errors that have a stack trace.
Source Files