xerrors

Documentation

Overview

Package xerrors provides structured application errors with stable typed codes, cause chaining, and key-value context fields.

Every error carries a machine-readable Code (gRPC-aligned wire value), a human-readable message, an optional cause, and optional structured fields. *Err implements errs.CodedError and errs.ContextualError from contracts, enabling logz to enrich log records automatically without importing this package.

Usage:

// Named constructors for common codes
err := xerrors.NotFound("user %s not found", userID)
err := xerrors.InvalidInput("email is required")

// Builder pattern for structured context
err := xerrors.New(xerrors.ErrInvalidInput, "validation failed").
    WithContext("field", "email").
    WithContext("rule", "required").
    WithError(cause)

// Inspecting errors
var e *xerrors.Err
if errors.As(err, &e) {
    switch e.Code() {
    case xerrors.ErrNotFound:
        // handle 404
    }
}

Index

• type Code
  • func (c Code) Description() string
• type Err
  • func Aborted(msg string, args ...any) *Err
  • func AlreadyExists(msg string, args ...any) *Err
  • func Cancelled(msg string, args ...any) *Err
  • func DataLoss(msg string, args ...any) *Err
  • func DeadlineExceeded(msg string, args ...any) *Err
  • func Gone(msg string, args ...any) *Err
  • func Internal(msg string, args ...any) *Err
  • func InvalidInput(msg string, args ...any) *Err
  • func New(code Code, message string) *Err
  • func NotFound(msg string, args ...any) *Err
  • func NotImplemented(msg string, args ...any) *Err
  • func OutOfRange(msg string, args ...any) *Err
  • func PermissionDenied(msg string, args ...any) *Err
  • func PreconditionFailed(msg string, args ...any) *Err
  • func RateLimited(msg string, args ...any) *Err
  • func Unauthorized(msg string, args ...any) *Err
  • func Unavailable(msg string, args ...any) *Err
  • func Wrap(code Code, message string, err error) *Err
  • func (e *Err) Code() Code
  • func (e *Err) Detailed() string
  • func (e *Err) Error() string
  • func (e *Err) ErrorCode() string
  • func (e *Err) ErrorContext() map[string]any
  • func (e *Err) Fields() map[string]any
  • func (e *Err) MarshalJSON() ([]byte, error)
  • func (e *Err) Message() string
  • func (e *Err) PlatformCode() string
  • func (e *Err) Unwrap() error
  • func (e *Err) WithContext(key string, value any) *Err
  • func (e *Err) WithError(err error) *Err
  • func (e *Err) WithPlatformCode(code string) *Err

Types

type Code

type Code string

Code is the machine-readable error category. Wire values are stable across versions and are identical to gRPC status code names. HTTP mapping is the responsibility of the transport layer, not this package.

const (
	// ErrInvalidInput indicates the request contains malformed or invalid data.
	// HTTP 400 / gRPC INVALID_ARGUMENT.
	ErrInvalidInput Code = "INVALID_ARGUMENT"

	// ErrOutOfRange indicates a parameter or index exceeds the valid bounds.
	// Use when the value itself is well-formed but falls outside accepted limits
	// (e.g. page number past the last page, offset past end of file).
	// HTTP 400 / gRPC OUT_OF_RANGE.
	ErrOutOfRange Code = "OUT_OF_RANGE"

	// ErrUnauthorized indicates the request lacks valid authentication credentials.
	// HTTP 401 / gRPC UNAUTHENTICATED.
	ErrUnauthorized Code = "UNAUTHENTICATED"

	// ErrPermissionDenied indicates the authenticated caller lacks permission for
	// the operation. Authentication is not the issue.
	// HTTP 403 / gRPC PERMISSION_DENIED.
	ErrPermissionDenied Code = "PERMISSION_DENIED"

	// ErrNotFound indicates the requested resource does not exist.
	// HTTP 404 / gRPC NOT_FOUND.
	ErrNotFound Code = "NOT_FOUND"

	// ErrAlreadyExists indicates a resource with the same identifier already exists.
	// Use for creation conflicts (e.g. duplicate email on sign-up).
	// HTTP 409 / gRPC ALREADY_EXISTS.
	ErrAlreadyExists Code = "ALREADY_EXISTS"

	// ErrAborted indicates the operation was aborted due to a concurrent modification
	// or transaction conflict. Unlike ErrAlreadyExists (creation conflict) and
	// ErrPreconditionFailed (business rule), this signals the caller may retry.
	// HTTP 409 / gRPC ABORTED.
	ErrAborted Code = "ABORTED"

	// ErrGone indicates the resource existed but has been permanently removed.
	// Unlike ErrNotFound, this signals the caller should not retry.
	// HTTP 410 / non-standard gRPC extension.
	ErrGone Code = "GONE"

	// ErrPreconditionFailed indicates a required business condition was not met.
	// The input is valid but a rule blocks the action (e.g. "cannot delete an
	// account with active subscriptions").
	// HTTP 412 / gRPC FAILED_PRECONDITION.
	ErrPreconditionFailed Code = "FAILED_PRECONDITION"

	// ErrRateLimited indicates the caller has exceeded a rate limit or quota.
	// HTTP 429 / gRPC RESOURCE_EXHAUSTED.
	ErrRateLimited Code = "RESOURCE_EXHAUSTED"

	// ErrCancelled indicates the operation was cancelled by the caller.
	// HTTP 499 / gRPC CANCELLED.
	ErrCancelled Code = "CANCELLED"

	// ErrInternal indicates an unexpected server-side failure.
	// Use a more specific code when one applies.
	// HTTP 500 / gRPC INTERNAL.
	ErrInternal Code = "INTERNAL"

	// ErrDataLoss indicates unrecoverable data loss or corruption.
	// Reserved for storage-layer integrity failures.
	// HTTP 500 / gRPC DATA_LOSS.
	ErrDataLoss Code = "DATA_LOSS"

	// ErrNotImplemented indicates the requested operation has not been implemented.
	// HTTP 501 / gRPC UNIMPLEMENTED.
	ErrNotImplemented Code = "UNIMPLEMENTED"

	// ErrUnavailable indicates the service is temporarily unable to handle requests.
	// HTTP 503 / gRPC UNAVAILABLE.
	ErrUnavailable Code = "UNAVAILABLE"

	// ErrDeadlineExceeded indicates the operation timed out before completing.
	// HTTP 504 / gRPC DEADLINE_EXCEEDED.
	ErrDeadlineExceeded Code = "DEADLINE_EXCEEDED"
)

func (Code) Description

func (c Code) Description() string

Description returns a human-readable description for the code. Unknown codes return their raw string value.

type Err

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

Err is a structured application error carrying a Code, a human-readable message, an optional cause, and optional key-value context fields.

It implements the standard error interface, errors.Unwrap for cause chaining, and json.Marshaler for API responses. It also satisfies errs.CodedError and errs.ContextualError from contracts, enabling logz to enrich log records automatically without importing this package.

Use the builder methods WithContext, WithError, and WithPlatformCode to attach additional information after construction:

err := xerrors.New(xerrors.ErrInvalidInput, "validation failed").
    WithContext("field", "email").
    WithContext("rule", "required").
    WithError(cause)

func Aborted

func Aborted(msg string, args ...any) *Err

Aborted creates an Err with ErrAborted code.

func AlreadyExists

func AlreadyExists(msg string, args ...any) *Err

AlreadyExists creates an Err with ErrAlreadyExists code.

func Cancelled

func Cancelled(msg string, args ...any) *Err

Cancelled creates an Err with ErrCancelled code.

func DataLoss

func DataLoss(msg string, args ...any) *Err

DataLoss creates an Err with ErrDataLoss code.

func DeadlineExceeded

func DeadlineExceeded(msg string, args ...any) *Err

DeadlineExceeded creates an Err with ErrDeadlineExceeded code.

func Gone

func Gone(msg string, args ...any) *Err

Gone creates an Err with ErrGone code.

func Internal

func Internal(msg string, args ...any) *Err

Internal creates an Err with ErrInternal code.

func InvalidInput

func InvalidInput(msg string, args ...any) *Err

InvalidInput creates an Err with ErrInvalidInput code.

func New

func New(code Code, message string) *Err

New creates an Err with the given code and message. No cause is set.

func NotFound

func NotFound(msg string, args ...any) *Err

NotFound creates an Err with ErrNotFound code.

func NotImplemented

func NotImplemented(msg string, args ...any) *Err

NotImplemented creates an Err with ErrNotImplemented code.

func OutOfRange

func OutOfRange(msg string, args ...any) *Err

OutOfRange creates an Err with ErrOutOfRange code.

func PermissionDenied

func PermissionDenied(msg string, args ...any) *Err

PermissionDenied creates an Err with ErrPermissionDenied code.

func PreconditionFailed

func PreconditionFailed(msg string, args ...any) *Err

PreconditionFailed creates an Err with ErrPreconditionFailed code.

func RateLimited

func RateLimited(msg string, args ...any) *Err

RateLimited creates an Err with ErrRateLimited code.

func Unauthorized

func Unauthorized(msg string, args ...any) *Err

Unauthorized creates an Err with ErrUnauthorized code.

func Unavailable

func Unavailable(msg string, args ...any) *Err

Unavailable creates an Err with ErrUnavailable code.

func Wrap

func Wrap(code Code, message string, err error) *Err

Wrap creates an Err that wraps an existing error with a code and message. The wrapped error is accessible via errors.Is, errors.As, and Err.Unwrap.

func (*Err) Code

func (e *Err) Code() Code

Code returns the typed error code.

func (*Err) Detailed

func (e *Err) Detailed() string

Detailed returns a verbose string useful for debugging. Format: "code: X | message: Y | cause: Z | fields: {...}"

func (*Err) Error

func (e *Err) Error() string

Error implements the error interface. Format: "INVALID_ARGUMENT: username is required → original cause"

func (*Err) ErrorCode

func (e *Err) ErrorCode() string

ErrorCode satisfies errs.CodedError. logz calls this to append error_code to log records without importing this package.

func (*Err) ErrorContext

func (e *Err) ErrorContext() map[string]any

ErrorContext satisfies errs.ContextualError. logz calls this to append context fields to log records. The returned map is read-only by logz; use Fields() if you need a safe copy.

func (*Err) Fields

func (e *Err) Fields() map[string]any

Fields returns a shallow copy of the context fields. Returns an empty (non-nil) map if no fields have been set.

func (*Err) MarshalJSON

func (e *Err) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler. Output: {"code":"NOT_FOUND","platform_code":"...","message":"...","fields":{...}} platform_code and fields are omitted when empty.

func (*Err) Message

func (e *Err) Message() string

Message returns the human-readable error message.

func (*Err) PlatformCode

func (e *Err) PlatformCode() string

PlatformCode returns the platform-level error code, or "" if none was set.

func (*Err) Unwrap

func (e *Err) Unwrap() error

Unwrap returns the underlying cause, enabling errors.Is and errors.As to walk the full cause chain.

func (*Err) WithContext

func (e *Err) WithContext(key string, value any) *Err

WithContext adds a key-value pair to the error's context fields and returns the receiver for chaining. Calling it multiple times with the same key overwrites the previous value.

func (*Err) WithError

func (e *Err) WithError(err error) *Err

WithError sets the underlying cause and returns the receiver for chaining.

func (*Err) WithPlatformCode

func (e *Err) WithPlatformCode(code string) *Err

WithPlatformCode sets a platform-level error code and returns the receiver for chaining. Platform codes are domain-specific identifiers (e.g. "EMPLOYEE_NOT_FOUND") intended for consuming applications — such as a frontend — that need to map errors to localised user-facing messages.

Platform codes are optional. Errors that have no user-actionable meaning (e.g. 500 internal errors) should not carry one.