errors

Documentation

Overview

Package errors provides enterprise-grade error handling for the QR code library. All errors implement the DomainError interface, supporting structured error codes, retryability classification, metadata propagation, and HTTP status mapping.

Usage

// Create a new domain error
err := errors.New(errors.ErrCodeValidation, "invalid input")

// Wrap an existing error with context
err := errors.Wrap(errors.ErrCodeEncoding, "encode failed", innerErr)

// Check error codes
if errors.IsCode(err, errors.ErrCodeValidation) { ... }

// Add metadata
err = err.WithMeta("field", "email").WithMeta("value", "bad")

// Check retryability
if errors.IsRetryable(err) { ... }

Index

• Variables
• func As(err error, target **QRCodeError) bool
• func HTTPStatus(err error) int
• func IsCode(err error, code ErrorCode) bool
• func IsRetryable(err error) bool
• func JoinErrors(errs ...error) error
• func Recover() error
• func SafeExecute(fn func() error) (err error)
• type BatchError
  • func NewBatchError(total int) *BatchError
  • func (be *BatchError) Error() string
  • func (be *BatchError) Get(idx int) error
  • func (be *BatchError) Len() int
  • func (be *BatchError) Set(idx int, err error)
• type DomainError
• type ErrorCode
• type QRCodeError
  • func New(code ErrorCode, message string) *QRCodeError
  • func Wrap(code ErrorCode, message string, cause error) *QRCodeError
  • func Wrapf(code ErrorCode, format string, args ...any) *QRCodeError
  • func (e *QRCodeError) Code() ErrorCode
  • func (e *QRCodeError) Error() string
  • func (e *QRCodeError) HTTPStatus() int
  • func (e *QRCodeError) Metadata() map[string]any
  • func (e *QRCodeError) Retryable() bool
  • func (e *QRCodeError) Unwrap() error
  • func (e *QRCodeError) WithMeta(key string, value any) *QRCodeError
  • func (e *QRCodeError) WithRetryable(retryable bool) *QRCodeError

Variables

var (
	// ErrClosed is returned when operations are attempted on a closed client.
	ErrClosed = New(ErrCodeClosed, "client is closed")

	// ErrDataTooLong is returned when the input data exceeds the maximum
	// capacity for the selected error correction level.
	ErrDataTooLong = New(ErrCodeDataTooLong, "data too long for QR code")

	// ErrInvalidConfig is returned when a configuration fails validation.
	ErrInvalidConfig = New(ErrCodeConfig, "invalid configuration")

	// ErrNilPayload is returned when a nil payload is provided.
	ErrNilPayload = New(ErrCodePayload, "payload is nil")
)

Functions

func As

func As(err error, target **QRCodeError) bool

As is a convenience wrapper around errors.As for QRCodeError.

func HTTPStatus

func HTTPStatus(err error) int

HTTPStatus returns the recommended HTTP status code for the given error. For non-DomainError errors, it returns 500 (Internal Server Error).

func IsCode

func IsCode(err error, code ErrorCode) bool

IsCode reports whether err (or any wrapped error in its chain) is a QRCodeError with the given code.

func IsRetryable

func IsRetryable(err error) bool

IsRetryable reports whether the error (or any wrapped DomainError in its chain) is retryable.

func JoinErrors

func JoinErrors(errs ...error) error

JoinErrors combines multiple errors into a single error. Nil errors are filtered out. If only one non-nil error remains, it is returned directly. Otherwise, a joined error is returned.

func Recover

func Recover() error

Recover recovers from a panic and returns it as an error. Useful in goroutine wrappers to prevent panics from crashing the process.

func SafeExecute

func SafeExecute(fn func() error) (err error)

SafeExecute runs fn and converts any panic into an error.

Types

type BatchError

type BatchError struct {
	Errors map[int]error
	Total  int
	// contains filtered or unexported fields
}

BatchError collects errors from batch operations, mapping item indices to their respective errors.

func NewBatchError

func NewBatchError(total int) *BatchError

NewBatchError creates a new BatchError for the given total item count. If total <= 0, it defaults to 0.

func (*BatchError) Error

func (be *BatchError) Error() string

Error returns a human-readable summary of the batch errors.

func (*BatchError) Get

func (be *BatchError) Get(idx int) error

Get retrieves the error for the given item index, or nil if none.

func (*BatchError) Len

func (be *BatchError) Len() int

Len returns the number of failed items.

func (*BatchError) Set

func (be *BatchError) Set(idx int, err error)

Set records an error for the given item index.

type DomainError

type DomainError interface {
	error
	// Code returns the machine-readable error code.
	Code() ErrorCode
	// Retryable reports whether the operation that caused this error
	// can reasonably be retried. Examples of retryable errors include
	// timeouts, temporary resource exhaustion, and rate limiting.
	// Non-retryable errors include validation failures and encoding errors.
	Retryable() bool
	// Metadata returns a copy of the error's metadata map.
	// Returns nil if no metadata has been attached.
	Metadata() map[string]any
}

DomainError is the core error interface for all library errors. It extends the standard error interface with structured error classification.

type ErrorCode

type ErrorCode string

ErrorCode is a machine-readable identifier for error categories.

const (
	ErrCodeUnknown     ErrorCode = "UNKNOWN"
	ErrCodeValidation  ErrorCode = "VALIDATION"
	ErrCodeEncoding    ErrorCode = "ENCODING"
	ErrCodeRendering   ErrorCode = "RENDERING"
	ErrCodeTimeout     ErrorCode = "TIMEOUT"
	ErrCodeClosed      ErrorCode = "CLOSED"
	ErrCodePayload     ErrorCode = "PAYLOAD"
	ErrCodeBatch       ErrorCode = "BATCH"
	ErrCodeDataTooLong ErrorCode = "DATA_TOO_LONG"
	ErrCodeFileWrite   ErrorCode = "FILE_WRITE"
	ErrCodeStorage     ErrorCode = "STORAGE"
	ErrCodeConfig      ErrorCode = "CONFIG"
	ErrCodeInternal    ErrorCode = "INTERNAL"
)

type QRCodeError

type QRCodeError struct {
	Message string
	Cause   error
	Meta    map[string]any
	// contains filtered or unexported fields
}

QRCodeError is the standard error type for the QR code library. It implements the DomainError interface and supports error wrapping via errors.Is / errors.As compatibility.

func New

func New(code ErrorCode, message string) *QRCodeError

New creates a new QRCodeError with the given code and message.

func Wrap

func Wrap(code ErrorCode, message string, cause error) *QRCodeError

Wrap creates a new QRCodeError that wraps an existing cause error. If cause is nil, it behaves like New.

func Wrapf

func Wrapf(code ErrorCode, format string, args ...any) *QRCodeError

Wrapf creates a new QRCodeError with a formatted message wrapping a cause.

func (*QRCodeError) Code

func (e *QRCodeError) Code() ErrorCode

Code returns the error's category code.

func (*QRCodeError) Error

func (e *QRCodeError) Error() string

Error returns a human-readable error string including the code, message, and optional cause chain.

func (*QRCodeError) HTTPStatus

func (e *QRCodeError) HTTPStatus() int

HTTPStatus returns the recommended HTTP status code for this error.

func (*QRCodeError) Metadata

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

Metadata returns a shallow copy of the error's metadata, or nil if none exists.

func (*QRCodeError) Retryable

func (e *QRCodeError) Retryable() bool

Retryable reports whether the operation can be retried. By default, TIMEOUT, INTERNAL, and STORAGE errors are retryable. Use WithRetryable() to override per-instance.

func (*QRCodeError) Unwrap

func (e *QRCodeError) Unwrap() error

Unwrap supports error chain traversal via errors.Is / errors.As.

func (*QRCodeError) WithMeta

func (e *QRCodeError) WithMeta(key string, value any) *QRCodeError

WithMeta attaches a key-value pair to the error's metadata. It returns a new QRCodeError with the metadata merged; the original is unchanged.

func (*QRCodeError) WithRetryable

func (e *QRCodeError) WithRetryable(retryable bool) *QRCodeError

WithRetryable sets a per-instance retryability override. This overrides the default retryability derived from the error code.