errors

Documentation

Overview

Package errors defines portable application error primitives and the problem document model used at HTTP transport boundaries.

Index

• func As(err error, target **Error) bool
• func Is(err error, code Code) bool
• type Code
  • func CodeOf(err error) Code
  • func (c Code) HTTPStatus() int
  • func (c Code) HTTPTitle() string
• type Error
  • func E(code Code, message string, err error) *Error
  • func Wrap(code Code, message string, err error) *Error
  • func (e *Error) Error() string
  • func (e *Error) StatusCode() int
  • func (e *Error) Unwrap() error
• type Problem
  • func ToProblem(err error) Problem

Functions

func As

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

As unwraps the error chain to find a *Error. Delegates to the standard library errors.As which handles both single-error and multi-error (errors.Join) unwrap chains.

func Is

func Is(err error, code Code) bool

Is reports whether the target error has the given code. Useful for checking error classification without a type assertion.

Types

type Code

type Code string

Code identifies an application-level error class.

const (
	CodeInvalidArgument Code = "invalid_argument"
	CodeUnauthenticated Code = "unauthenticated"
	CodeForbidden       Code = "forbidden"
	CodeNotFound        Code = "not_found"
	CodeConflict        Code = "conflict"
	CodeRateLimited     Code = "rate_limited"
	CodeTimeout         Code = "timeout"
	CodeUnavailable     Code = "unavailable"
	CodeInternal        Code = "internal"
)

func CodeOf

func CodeOf(err error) Code

Code extracts the platform error code from an error. Returns CodeInternal if the error is not a platform error.

func (Code) HTTPStatus

func (c Code) HTTPStatus() int

HTTPStatus maps a Code to its canonical HTTP status code.

func (Code) HTTPTitle

func (c Code) HTTPTitle() string

HTTPTitle maps a Code to a human-readable title for problem documents.

type Error

type Error struct {
	Code    Code
	Message string
	Err     error
}

Error is the platform error model.

func E

func E(code Code, message string, err error) *Error

E creates a new platform error.

func Wrap

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

Wrap wraps an existing error under a platform error code. The original error is preserved for logging and tracing.

func (*Error) Error

func (e *Error) Error() string

func (*Error) StatusCode

func (e *Error) StatusCode() int

StatusCode implements the httpx ErrorEncoder status-code interface. It returns the canonical HTTP status for the error code, allowing httpx.DefaultErrorEncoder to map platform errors to correct HTTP statuses without a direct import dependency from httpx → errors.

func (*Error) Unwrap

func (e *Error) Unwrap() error

Unwrap exposes the wrapped error for errors.Is / errors.As.

type Problem

type Problem struct {
	Type      string `json:"type,omitempty"`
	Title     string `json:"title"`
	Status    int    `json:"status"`
	Code      string `json:"code"`
	Detail    string `json:"detail,omitempty"`
	Instance  string `json:"instance,omitempty"`
	RequestID string `json:"request_id,omitempty"`
	TraceID   string `json:"trace_id,omitempty"`
}

Problem is the application/problem+json response shape (RFC 7807).

func ToProblem

func ToProblem(err error) Problem

ToProblem converts a platform error to a Problem document. Instance, RequestID, and TraceID should be set by the transport layer.

For server-side error codes (5xx), the Detail field is intentionally left empty to prevent internal implementation details from leaking to clients. Client-facing error codes (4xx) include the message in Detail since these are expected to contain safe, actionable information.