errors

Documentation

Overview

Package errors implements the spec §4 error envelope + exit-code taxonomy.

Every non-zero exit path funnels through Write, which either unwraps an *E (a structured sku error) or boxes a plain Go error as a generic_error envelope. The exit code taxonomy is stable — agents depend on it per spec §4.

Index

• func ValidationReasons() []string
• func Write(w io.Writer, err error) int
• type CatalogSchema
  • func ErrorCatalog() CatalogSchema
• type Code
  • func (c Code) ExitCode() int
• type CodeEntry
• type E
  • func NotFound(provider, service string, appliedFilters map[string]any, suggestion string) *E
  • func Validation(reason, flag, value string, hint string) *E
  • func (e *E) Error() string

Functions

func ValidationReasons

func ValidationReasons() []string

ValidationReasons is the closed set of reason strings allowed under details.reason for a CodeValidation envelope.

func Write

func Write(w io.Writer, err error) int

Write marshals err to the §4 JSON envelope on w and returns the exit code the process should use. A nil err writes nothing and returns 0. Any non-*E error is boxed as CodeGeneric.

Types

type CatalogSchema

type CatalogSchema struct {
	Entries       map[string]CodeEntry `json:"codes"`
	SchemaVersion int                  `json:"schema_version"`
}

CatalogSchema is the top-level envelope emitted by `sku schema --errors`. It pins every error Code to a fixed details shape so agents can author envelope-aware retry / fallback logic without spelunking through spec text. SchemaVersion bumps whenever a code is added, removed, or its DetailsFields list changes (see spec §4 error envelope).

func ErrorCatalog

func ErrorCatalog() CatalogSchema

ErrorCatalog returns the in-memory catalog consumed by `sku schema --errors` and (eventually) by golden-envelope tests. The returned value is safe to mutate by callers — each call builds a fresh map.

type Code

type Code string

Code is the stable error-code enum emitted in the envelope's error.code and mapped to a process exit code via ExitCode.

const (
	CodeOK          Code = ""              // exit 0
	CodeGeneric     Code = "generic_error" // exit 1
	CodeAuth        Code = "auth"          // exit 2
	CodeNotFound    Code = "not_found"     // exit 3
	CodeValidation  Code = "validation"    // exit 4
	CodeRateLimited Code = "rate_limited"  // exit 5
	CodeConflict    Code = "conflict"      // exit 6
	CodeServer      Code = "server"        // exit 7
	CodeStaleData   Code = "stale_data"    // exit 8
)

Exit-code constants — one per spec §4 taxonomy entry.

func (Code) ExitCode

func (c Code) ExitCode() int

ExitCode returns the process exit code for this error code.

type CodeEntry

type CodeEntry struct {
	ExitCode      int      `json:"exit_code"`
	Description   string   `json:"description"`
	DetailsFields []string `json:"details_fields"`
	// Reasons is non-empty only for "validation", which subdivides further.
	Reasons []string `json:"reasons,omitempty"`
}

CodeEntry describes one row of the spec §4 error-code taxonomy.

type E

type E struct {
	Code       Code           `json:"code"`
	Message    string         `json:"message"`
	Suggestion string         `json:"suggestion,omitempty"`
	Details    map[string]any `json:"details,omitempty"`
}

E is the canonical structured sku error. It implements the error interface and renders as the §4 JSON envelope when passed to Write.

func NotFound

func NotFound(provider, service string, appliedFilters map[string]any, suggestion string) *E

NotFound builds an E with CodeNotFound and the common details shape (§4).

func Validation

func Validation(reason, flag, value string, hint string) *E

Validation builds an E with CodeValidation and the common details shape (§4).

func (*E) Error

func (e *E) Error() string

Error implements error.