apperr

Documentation

Overview

Package apperr defines the standard structured error type used across go-core and all consuming services.

All errors that cross a package boundary or reach the HTTP layer must be *AppError values. Use the constructor helpers:

apperr.BadRequest("invalid input")
apperr.NotFound("user not found")
apperr.Internal(err)
apperr.Wrap(err, "context message", apperr.CodeInternal)

The error carries a semantic Code (used to map to HTTP status), a user-friendly Message, a LogLevel hint, and the source file/line for diagnostics.

Index

• func GetHTTPStatus(err error) int
• type AppError
  • func BadRequest(message string) *AppError
  • func Forbidden(message string) *AppError
  • func Internal(err error) *AppError
  • func New(err error, message string, code Code) *AppError
  • func NotFound(message string) *AppError
  • func Unauthorized(message string) *AppError
  • func Wrap(err error, message string, code Code) *AppError
  • func WrapPreserve(err error, message string) *AppError
  • func (e *AppError) Error() string
  • func (e *AppError) Unwrap() error
  • func (e *AppError) WithFields(fields map[string]string) *AppError
  • func (e *AppError) WithLog(level Level) *AppError
• type Code
• type Level

Functions

func GetHTTPStatus

func GetHTTPStatus(err error) int

GetHTTPStatus extracts the HTTP status code from an error. It unwraps error chains, so errors wrapped with fmt.Errorf("%w", appErr) work correctly.

Types

type AppError

type AppError struct {
	Err      error             // The original error
	Code     Code              // Semantic error code
	Message  string            // User-friendly message
	LogLevel Level             // Suggestion for logging level
	Fields   map[string]string // Optional field-level detail (e.g. for 409 conflicts)
	File     string            // Source file
	Line     int               // Source line
}

AppError is the standard error type for the application. It wraps the original error and adds context like HTTP status, user message, and log level.

func BadRequest

func BadRequest(message string) *AppError

func Forbidden

func Forbidden(message string) *AppError

func Internal

func Internal(err error) *AppError

func New

func New(err error, message string, code Code) *AppError

New creates a generic AppError.

func NotFound

func NotFound(message string) *AppError

func Unauthorized

func Unauthorized(message string) *AppError

func Wrap

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

Wrap wraps err in a new AppError with the given message and code. If err is already an AppError, it is preserved as the cause. Unlike the old behavior, the new message and code are ALWAYS applied — use this when you want to add context at a higher layer.

func WrapPreserve

func WrapPreserve(err error, message string) *AppError

WrapPreserve wraps err but preserves the original AppError's status code and log level. Use this when you want to add a message without changing how the error is classified.

func (*AppError) Error

func (e *AppError) Error() string

func (*AppError) Unwrap

func (e *AppError) Unwrap() error

func (*AppError) WithFields

func (e *AppError) WithFields(fields map[string]string) *AppError

WithFields attaches field-level detail to the error (e.g. {"code": "already taken"}). The error handler will include these in the response body.

func (*AppError) WithLog

func (e *AppError) WithLog(level Level) *AppError

WithLog sets the log level.

type Code

type Code string

Code represents a semantic error category

const (
	CodeInternal         Code = "internal_error"
	CodeNotFound         Code = "not_found"
	CodeBadRequest       Code = "bad_request"
	CodeUnauthenticated  Code = "unauthenticated"
	CodePermissionDenied Code = "permission_denied"
	CodeInvalidArgument  Code = "invalid_argument"
	CodeAlreadyExists    Code = "already_exists"
	CodeValidationError  Code = "validation_error"
)

type Level

type Level string

Level defines the log level for the error.

const (
	LevelNone  Level = "none"
	LevelInfo  Level = "info"
	LevelWarn  Level = "warn"
	LevelError Level = "error"
)