errors

Documentation

Overview

Package errors defines the error taxonomy shared by every frontend of the kit: one coded error drives the CLI exit code, the HTTP status code, and the MCP JSON-RPC error code alike, so transport implementations never need to interpret command-specific error strings.

Index

• func Cause(err error) error
• func Errorf(kind Kind, format string, a ...any) error
• func ExitCode(k Kind) int
• func HTTPStatus(k Kind) int
• func JSONRPCCode(k Kind) int
• func New(kind Kind, msg string) error
• func Wrap(kind Kind, cause error) error
• func WrapMsg(kind Kind, cause error, msg string) error
• type CodedError
  • func (e *CodedError) Error() string
  • func (e *CodedError) Unwrap() error
• type Kind
  • func Classify(err error) Kind

Functions

func Cause

func Cause(err error) error

Cause unwraps coded errors and returns the innermost known cause.

func Errorf

func Errorf(kind Kind, format string, a ...any) error

Errorf builds a coded error with a formatted message.

func ExitCode

func ExitCode(k Kind) int

ExitCode maps a Kind to a CLI process exit code.

func HTTPStatus

func HTTPStatus(k Kind) int

HTTPStatus maps a Kind to its natural HTTP status code.

func JSONRPCCode

func JSONRPCCode(k Kind) int

JSONRPCCode maps a Kind to a JSON-RPC 2.0 error code. Standard codes are negative; application-defined server errors live in the -32000..-32099 range both JSON-RPC and MCP reserve for this purpose.

func New

func New(kind Kind, msg string) error

New builds a coded error with no cause.

func Wrap

func Wrap(kind Kind, cause error) error

Wrap builds a coded error whose message is the cause's.

func WrapMsg

func WrapMsg(kind Kind, cause error, msg string) error

WrapMsg builds a coded error with both a message and a cause.

Types

type CodedError

type CodedError struct {
	Kind    Kind
	Message string
	// contains filtered or unexported fields
}

CodedError wraps a cause with a Kind and an optional message.

func (*CodedError) Error

func (e *CodedError) Error() string

func (*CodedError) Unwrap

func (e *CodedError) Unwrap() error

Unwrap exposes the cause for errors.Is / errors.As.

type Kind

type Kind string

Kind classifies an error. Frontends translate a Kind into their own error representation via HTTPStatus, ExitCode and JSONRPCCode.

const (
	// KindInvalidInput means the caller provided malformed or invalid
	// arguments (missing required fields, failed validation, bad enums).
	KindInvalidInput Kind = "invalid_input"
	// KindUnauthorized means the caller must authenticate before retrying.
	KindUnauthorized Kind = "unauthorized"
	// KindForbidden means the caller authenticated but lacks permission.
	KindForbidden Kind = "forbidden"
	// KindNotFound means the target of the operation does not exist.
	KindNotFound Kind = "not_found"
	// KindConflict means the operation collides with existing state.
	KindConflict Kind = "conflict"
	// KindCanceled means the operation was canceled by the caller.
	KindCanceled Kind = "canceled"
	// KindUnavailable means a dependency is temporarily down.
	KindUnavailable Kind = "unavailable"
	// KindInternal is the fallback for unclassified failures.
	KindInternal Kind = "internal"
	// KindNone is what Classify returns for a nil error.
	KindNone Kind = ""
)

func Classify

func Classify(err error) Kind

Classify walks the error chain and returns the first coded Kind. Unclassified non-nil errors fall back to KindInternal; a nil error is KindNone.