errs

Documentation

Overview

Package errs defines the typed error taxonomy shared by every kit-based CLI and its one true mapping to CLI exit codes, HTTP status codes, and MCP error objects. A domain returns these so the surfaces classify failures the same way everywhere, replacing the bespoke error-to-exit-code map each repo used to hand-roll.

Index

• func ExitCode(err error) int
• func HTTPStatus(err error) int
• type Error
  • func NeedAuth(format string, args ...any) *Error
  • func Network(format string, args ...any) *Error
  • func New(kind Kind, format string, args ...any) *Error
  • func NoResults(format string, args ...any) *Error
  • func NotFound(format string, args ...any) *Error
  • func RateLimited(format string, args ...any) *Error
  • func Unsupported(format string, args ...any) *Error
  • func Usage(format string, args ...any) *Error
  • func Wrap(kind Kind, err error, format string, args ...any) *Error
  • func (e *Error) Error() string
  • func (e *Error) Unwrap() error
• type Kind
  • func KindOf(err error) Kind

Functions

func ExitCode

func ExitCode(err error) int

ExitCode maps an error to the stable CLI exit code.

func HTTPStatus

func HTTPStatus(err error) int

HTTPStatus maps an error to the HTTP status the API surface returns.

Types

type Error

type Error struct {
	Kind Kind
	Msg  string
	Err  error
}

Error is a classified error carrying a Kind plus the underlying cause.

func NeedAuth

func NeedAuth(format string, args ...any) *Error

func Network

func Network(format string, args ...any) *Error

func New

func New(kind Kind, format string, args ...any) *Error

New builds a classified error from a kind and a message (printf-style).

func NoResults

func NoResults(format string, args ...any) *Error

func NotFound

func NotFound(format string, args ...any) *Error

func RateLimited

func RateLimited(format string, args ...any) *Error

func Unsupported

func Unsupported(format string, args ...any) *Error

func Usage

func Usage(format string, args ...any) *Error

Convenience constructors for the common kinds.

func Wrap

func Wrap(kind Kind, err error, format string, args ...any) *Error

Wrap classifies an existing error under a kind, keeping it unwrappable.

func (*Error) Error

func (e *Error) Error() string

func (*Error) Unwrap

func (e *Error) Unwrap() error

type Kind

type Kind int

Kind is the classification of a failure. The zero value (KindOK) means no error. Each kind has a fixed CLI exit code and HTTP status (see Code/Status).

const (
	KindOK          Kind = iota // success
	KindGeneric                 // generic failure (exit 1)
	KindUsage                   // bad flags/args (exit 2)
	KindNoResults               // the query yielded nothing (exit 3)
	KindNeedAuth                // credentials required or invalid (exit 4)
	KindRateLimited             // upstream exhausted after retries (exit 5)
	KindNotFound                // entity/id does not exist (exit 6)
	KindUnsupported             // capability not available for this site (exit 7)
	KindNetwork                 // transport failure (exit 8)
)

func KindOf

func KindOf(err error) Kind

KindOf returns the Kind of any error: an *Error's kind, or KindGeneric for a non-nil unclassified error, or KindOK for nil.