errors

Documentation

Overview

Package errors provides a shared StatusError type that carries an HTTP status code, a user-facing message, and an optional wrapped cause.

pkg/ packages cannot import api/internal/errors (Go internal-package visibility), so domain errors defined in pkg/ use StatusError instead. The API server's generic error handler (respondWithError in router.go) already has a duck-type fallback that checks for StatusCode() int + Error() string, so StatusError values are handled automatically without any handler-level switch.

Usage as a sentinel:

var ErrSecretNotFound = &StatusError{
    Status:  http.StatusNotFound,
    Code:    "secret_not_found",
    Message: "secret not found",
}

Wrapping with detail:

return fmt.Errorf("lookup %s: %w", name, ErrSecretNotFound)

Checking at the handler:

errors.Is(err, ErrSecretNotFound)         // sentinel check
var se *errors.StatusError
errors.As(err, &se)                        // generic typed check
se.StatusCode()                            // 404

Index

• type StatusError
  • func NewStatusError(status int, code, message string) *StatusError
  • func (e *StatusError) Error() string
  • func (e *StatusError) StatusCode() int
  • func (e *StatusError) Unwrap() error

Types

type StatusError

type StatusError struct {
	Status  int    // HTTP status code (e.g. 404, 409, 412)
	Code    string // machine-readable error code (e.g. "secret_not_found")
	Message string // user-facing message (safe to expose — no secrets, no internal paths)
	Cause   error  // wrapped underlying error for logging/debugging
}

StatusError is a typed error that carries an HTTP status code and a user-facing message. It is the pkg/-side counterpart to api/internal/errors.APIError — both implement StatusCode() int so the generic error handler treats them uniformly.

func NewStatusError

func NewStatusError(status int, code, message string) *StatusError

NewStatusError creates a new StatusError with the given fields.

func (*StatusError) Error

func (e *StatusError) Error() string

Error implements the error interface. Returns the user-facing Message plus the Cause (if any) so server-side logs show the full chain. The HTTP handler uses Message directly (not Error()) so the Cause detail never leaks to the client.

func (*StatusError) StatusCode

func (e *StatusError) StatusCode() int

StatusCode returns the HTTP status code for this error. Used by the generic error handler's duck-type fallback.

func (*StatusError) Unwrap

func (e *StatusError) Unwrap() error

Unwrap returns the wrapped cause, enabling errors.Is and errors.As to traverse the chain.