errors

Documentation

Overview

Package errors provides structured error handling with context propagation and HTTP status code mapping.

Index

• type Error
  • func AsStructuredError(err error) *Error
  • func ConflictError(message string) *Error
  • func ExternalError(message string, cause error) *Error
  • func InternalError(message string, cause error) *Error
  • func NotFoundError(message string) *Error
  • func ValidationError(message string) *Error
  • func (e *Error) Error() string
  • func (e *Error) HTTPStatus() int
  • func (e *Error) ToResponse() ErrorResponse
  • func (e *Error) Unwrap() error
  • func (e *Error) WithContext(key string, value any) *Error
  • func (e *Error) WithField(key string, value any) *Error
• type ErrorResponse
• type ErrorType

Types

type Error

type Error struct {
	Type    ErrorType
	Message string
	Cause   error
	Context map[string]any
}

Error represents a structured error with type, message, and context.

func AsStructuredError

func AsStructuredError(err error) *Error

AsStructuredError converts any error into a structured Error. If err is already an *Error, returns it unchanged. Otherwise wraps it as an internal error.

func ConflictError

func ConflictError(message string) *Error

ConflictError creates a new conflict error (HTTP 409).

func ExternalError

func ExternalError(message string, cause error) *Error

ExternalError creates a new external service error (HTTP 502).

func InternalError

func InternalError(message string, cause error) *Error

InternalError creates a new internal error (HTTP 500).

func NotFoundError

func NotFoundError(message string) *Error

NotFoundError creates a new not-found error (HTTP 404).

func ValidationError

func ValidationError(message string) *Error

ValidationError creates a new validation error (HTTP 400).

func (*Error) Error

func (e *Error) Error() string

Error implements the error interface.

func (*Error) HTTPStatus

func (e *Error) HTTPStatus() int

HTTPStatus returns the appropriate HTTP status code for this error type.

func (*Error) ToResponse

func (e *Error) ToResponse() ErrorResponse

ToResponse converts an Error to an ErrorResponse for JSON serialization.

func (*Error) Unwrap

func (e *Error) Unwrap() error

Unwrap returns the underlying cause for errors.Is/As support.

func (*Error) WithContext

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

WithContext adds context fields to the error (chainable).

func (*Error) WithField

func (e *Error) WithField(key string, value any) *Error

WithField is an alias for WithContext (chainable).

type ErrorResponse

type ErrorResponse struct {
	Error   string         `json:"error"`
	Type    ErrorType      `json:"type"`
	Context map[string]any `json:"context,omitempty"`
}

ErrorResponse represents the JSON structure sent to clients.

type ErrorType

type ErrorType string

ErrorType represents the category of error for metrics and response formatting.

const (
	// TypeValidation indicates invalid input (HTTP 400)
	TypeValidation ErrorType = "validation"
	// TypeNotFound indicates resource not found (HTTP 404)
	TypeNotFound ErrorType = "not_found"
	// TypeConflict indicates resource conflict (HTTP 409)
	TypeConflict ErrorType = "conflict"
	// TypeInternal indicates server-side error (HTTP 500)
	TypeInternal ErrorType = "internal"
	// TypeExternal indicates external service error (HTTP 502/503)
	TypeExternal ErrorType = "external"
)