Documentation
¶
Overview ¶
Package errs defines the CLI's structured error taxonomy.
Agents and scripts consume the CLI's exit code + stable JSON error code to decide what to do next. Both come from this package:
- Kind is a stable string identifier (e.g. "auth_required") that survives across releases. Add new Kinds; never re-purpose old ones.
- ExitCode maps each Kind to a small integer in the range [1, 7], stable across releases. Exit code 130 is reserved for SIGINT (POSIX).
Error wraps the underlying cause but carries the classified Kind + the agent-facing message. Classify(err) walks an arbitrary error chain and produces a *Error; commands that already know the right kind can build one directly via Validation/AuthRequired/etc.
Index ¶
- type Error
- func AuthInvalid(cause error, message string) *Error
- func AuthRequired(message string) *Error
- func Classify(err error) *Error
- func New(kind Kind, format string, args ...any) *Error
- func NotFound(format string, args ...any) *Error
- func RateLimited(cause error) *Error
- func Validation(format string, args ...any) *Error
- func Wrap(kind Kind, cause error, format string, args ...any) *Error
- type Kind
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Error ¶
type Error struct {
Kind Kind
Message string
HTTPStatus int
// contains filtered or unexported fields
}
Error is the CLI's classified error type. It implements `error` and can wrap an underlying cause via Unwrap so callers can still use errors.Is against SDK sentinels.
func AuthInvalid ¶
AuthInvalid indicates the configured token was rejected by the server.
func AuthRequired ¶
AuthRequired indicates no token is configured.
func Classify ¶
Classify walks an arbitrary error chain and returns the *Error that best describes it. The function is idempotent: a *Error in flows straight back out. nil in returns nil out.
New SDK / runtime errors that need a distinct Kind should be added here so the entire CLI gains the correct exit code + JSON code at once.
func RateLimited ¶
RateLimited indicates the caller is being throttled by the API.
func Validation ¶
Validation is the common shortcut for command-body argument checks.
func Wrap ¶
Wrap builds a classified error that preserves the underlying cause. errors.Is(wrapped, sentinel) keeps working through the chain.
type Kind ¶
type Kind string
Kind is the agent-facing error identifier. The string value is the stable API contract — once shipped, do not rename.
const ( // KindInternal is the catch-all for unexpected errors. Exit 1. KindInternal Kind = "internal" // KindValidation covers bad CLI arguments, missing required flags, // or any pre-flight input problem the user can fix. Exit 2. KindValidation Kind = "validation" // KindAuthRequired means no token was supplied at all. Exit 3. KindAuthRequired Kind = "auth_required" // KindAuthInvalid means a token was supplied but the server rejected // it (401, 403, or session.CheckAuth failure). Exit 3. KindAuthInvalid Kind = "auth_invalid" // KindNotFound is HTTP 404 / "no such index" / "token id unknown". Exit 4. KindNotFound Kind = "not_found" // KindRateLimited is HTTP 429. Exit 5. KindRateLimited Kind = "rate_limited" // KindNetwork covers DNS failures, connection refused, request timeouts. Exit 6. KindNetwork Kind = "network" // KindBadRequest is HTTP 4xx that is not 401/403/404/429 — typically a // malformed query the user can fix. Exit 2 (alongside validation). KindBadRequest Kind = "bad_request" // KindCancelled means the user (or a parent process) sent SIGINT/SIGTERM // or cancelled the context. Exit 130 to match POSIX (128 + SIGINT). KindCancelled Kind = "cancelled" )
Source Files