Documentation
¶
Overview ¶
Package errors is wowapi's error taxonomy: a closed set of Kinds that map deterministically to HTTP status codes and stable machine codes, plus the structured Error type carried across every layer. The HTTP layer (kernel/ httpx) translates an *Error into an RFC 9457 problem-details body; anything that is not an *Error becomes an opaque 500 whose detail never reaches the wire. Contract: docs/blueprint/04 §5.
The taxonomy is intentionally closed — new failure modes pick an existing Kind rather than inventing wire contracts ad hoc.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Error ¶
type Error struct {
Kind Kind
Code string // stable machine code; defaults to Kind.DefaultCode()
Msg string // safe, user-facing
Op string // "requests.Service.Approve" — logs only
Fields []FieldError
Err error // wrapped cause (%w)
}
Error is the structured error carried across layers. Msg is user-safe; Op and the wrapped Err are for logs only and never reach the wire.
func E ¶
E constructs an *Error. msg is treated as a plain string (not a format string) so caller-supplied values can never turn into format verbs; use fmt.Sprintf at the call site if you need interpolation. args, if given, may be a single wrapped error and/or an Op string:
errors.E(KindNotFound, "not_found", "request not found")
errors.E(KindInternal, "internal", "load failed", cause, Op("svc.Load"))
func Validation ¶
func Validation(msg string, fields ...FieldError) *Error
Validation builds a KindValidation error carrying field errors.
type FieldError ¶
type FieldError struct {
Field string `json:"field"` // JSON path, e.g. "contacts[0].email"
Code string `json:"code"` // "required", "max_length", "invalid_format"
Message string `json:"message"` // safe for users
}
FieldError is one shape-validation failure, addressed by JSON path.
type Kind ¶
type Kind int
Kind is the closed set of error categories. Each maps to exactly one HTTP status and one machine code (see mapping below).
const ( KindInternal Kind = iota // default zero value: unmapped → 500 KindValidation KindUnauthenticated KindForbidden KindTenantIsolation KindNotFound KindConflict KindVersionConflict KindIdempotencyInFlight KindRuleViolation KindWorkflowState KindRateLimited KindExternal // KindIdempotencyExpired: a request presented an idempotency key whose // stored record has expired, so the original response can no longer be // replayed. Returned instead of silently re-executing the operation // (roadmap S5). Appended last to keep the earlier iota values stable. KindIdempotencyExpired )
func KindOf ¶
KindOf extracts the taxonomy Kind for any error: the nearest wrapped *Error's Kind, or KindInternal when none is present (unknown errors are 500s).
func (Kind) DefaultCode ¶
DefaultCode returns the taxonomy's machine code for k.
func (Kind) HTTPStatus ¶
HTTPStatus returns the HTTP status k maps to.
Source Files