Documentation
¶
Overview ¶
Package errors provides application error types and codes.
Index ¶
- Constants
- func Append(left, right error) error
- func As(err error, target any) bool
- func Combine(errs ...error) error
- func Errors(err error) []error
- func Is(err error, code ErrorCode) bool
- func IsPermanent(err error) bool
- func IsTransient(err error) bool
- func Join(errs ...error) error
- func LogError(logger *zap.Logger, msg string, err error)
- func LogErrors(logger *zap.Logger, msg string, combined error)
- func Sentinel(text string) error
- func StdIs(err, target error) bool
- func ToHTTPStatus(code ErrorCode) int
- func Unwrap(err error) error
- func Wrap(err error, code ErrorCode, message string) error
- func ZapError(err error) zap.Field
- func ZapFields(err *AppError) []zap.Field
- type AppError
- func Conflict(message string) *AppError
- func Forbidden(message string) *AppError
- func Ingestion(message string) *AppError
- func Internal(message string) *AppError
- func InvalidInput(message string) *AppError
- func New(code ErrorCode, message string) *AppError
- func NotFound(message string) *AppError
- func QualityFailed(message string) *AppError
- func Timeout(message string) *AppError
- func Unauthorized(message string) *AppError
- func Unavailable(message string) *AppError
- func Upstream(message string) *AppError
- func WithDetails(err *AppError, details map[string]string) *AppError
- type ErrorCode
Constants ¶
const ( // CodeUnknown is the fallback code for errors that are not AppErrors or carry no code. CodeUnknown ErrorCode = "UNKNOWN" // CodeInternal marks an unexpected server-side failure. CodeInternal ErrorCode = "INTERNAL" // CodeNotFound marks a missing resource. CodeNotFound ErrorCode = "NOT_FOUND" CodeUnauthorized ErrorCode = "UNAUTHORIZED" // CodeForbidden marks an authenticated caller lacking permission for the action. CodeForbidden ErrorCode = "FORBIDDEN" // CodeInvalidInput marks a malformed or otherwise rejected request payload. CodeInvalidInput ErrorCode = "INVALID_INPUT" // CodeConflict marks a state conflict (e.g. a duplicate or concurrent modification). CodeConflict ErrorCode = "CONFLICT" // CodeTimeout marks an operation that exceeded its deadline. CodeTimeout ErrorCode = "TIMEOUT" // CodeCanceled marks an operation that was canceled by the caller. CodeCanceled ErrorCode = "CANCELED" CodeUnavailable ErrorCode = "UNAVAILABLE" // CodeIngestion marks a failure in the document ingestion pipeline. CodeIngestion ErrorCode = "INGESTION_ERROR" // CodeQualityFailed marks a failed quality gate. CodeQualityFailed ErrorCode = "QUALITY_FAILED" // CodeUpstream marks a failure originating in an upstream dependency. CodeUpstream ErrorCode = "UPSTREAM" // CodeResourceExhausted marks a request rejected because a quota or budget is // spent. It is neither transient (retrying before the window resets only burns // the quota check) nor permanent (the request succeeds once the window resets). CodeResourceExhausted ErrorCode = "RESOURCE_EXHAUSTED" // ErrUnknown aliases CodeUnknown. ErrUnknown = CodeUnknown // ErrInternal aliases CodeInternal. ErrInternal = CodeInternal // ErrNotFound aliases CodeNotFound. ErrNotFound = CodeNotFound ErrUnauthorized = CodeUnauthorized // ErrForbidden aliases CodeForbidden. ErrForbidden = CodeForbidden // ErrInvalidInput aliases CodeInvalidInput. ErrInvalidInput = CodeInvalidInput // ErrConflict aliases CodeConflict. ErrConflict = CodeConflict // ErrTimeout aliases CodeTimeout. ErrTimeout = CodeTimeout ErrUnavailable = CodeUnavailable // ErrIngestion aliases CodeIngestion. ErrIngestion = CodeIngestion // ErrQualityFailed aliases CodeQualityFailed. ErrQualityFailed = CodeQualityFailed )
Error codes.
Variables ¶
This section is empty.
Functions ¶
func Append ¶
Append appends right into left, returning the combined error. Either value may be nil, in which case the other is returned unchanged. It delegates to multierr.Append.
func As ¶
As finds the first error in err's tree that matches target, and if one is found, sets target to that error value and returns true. Re-export of errors.As.
func Combine ¶
Combine merges multiple errors into a single error. nil errors are discarded. If all errors are nil, it returns nil. It delegates to multierr.Combine.
func Errors ¶
Errors extracts individual errors from a combined error. If the error is not a combined error, returns a single-element slice.
func IsPermanent ¶
IsPermanent returns true if the error represents a permanent failure that will not succeed on retry (not found, invalid input, unauthorized, forbidden, conflict). CodeResourceExhausted is not permanent: the request succeeds once the quota window resets.
func IsTransient ¶
IsTransient returns true if the error represents a transient failure that may succeed on retry (timeout, unavailable). CodeResourceExhausted is deliberately not transient: a spent quota does not recover within a retry backoff, only when its window resets.
func Join ¶
Join returns an error that wraps the given errors. Any nil error values are discarded. Re-export of errors.Join.
func LogError ¶
LogError logs a single error with structured AppError fields. Transient errors (timeout, unavailable) are logged at Warn level. All other errors are logged at Error level.
func LogErrors ¶
LogErrors logs a combined multi-error, emitting one log entry per individual error. Each error is logged via LogError with its own structured fields.
func Sentinel ¶
Sentinel creates a simple sentinel error value with the given message. Use this instead of importing the standard "errors" package for errors.New. For application errors with error codes, use New() instead.
func StdIs ¶
StdIs reports whether any error in err's tree matches target. Re-export of errors.Is. Named StdIs to avoid collision with the package-level Is(err, ErrorCode) function.
func ToHTTPStatus ¶
ToHTTPStatus maps an ErrorCode to the corresponding HTTP status code.
func Unwrap ¶
Unwrap returns the result of calling the Unwrap method on err. Re-export of errors.Unwrap.
Types ¶
type AppError ¶
type AppError struct {
// Err is the underlying wrapped error, if any.
Err error
// Details holds optional key-value context about the error.
Details map[string]string
// Code is the application-level error code.
Code ErrorCode
// Message is a human-readable description of the error.
Message string
// contains filtered or unexported fields
}
AppError represents an application error with code and context.
func InvalidInput ¶
InvalidInput creates an invalid input error.
func QualityFailed ¶
QualityFailed creates a quality gate failure error.
func Unauthorized ¶
Unauthorized creates an unauthorized error.
func Unavailable ¶
Unavailable creates an unavailable error.
func WithDetails ¶
WithDetails returns a copy of the error with additional details.
func (*AppError) MarshalLogObject ¶
func (e *AppError) MarshalLogObject(enc zapcore.ObjectEncoder) error
MarshalLogObject implements zapcore.ObjectMarshaler for AppError. Encodes code, message, the wrapped cause, the origin stack, and details (nested object). The cause and stack are what make a wrapped error diagnosable: without them, a generic "failed to query database" hides the real underlying failure (e.g. a Postgres "column does not exist").
func (*AppError) StackTrace ¶
StackTrace renders the captured origin stack as a newline-separated "func\n\tfile:line" trace, skipping the leading frames that belong to this errors package so the trace starts at the application code that created the error. Returns an empty string when no stack was captured.
type ErrorCode ¶
type ErrorCode string
ErrorCode represents application error codes.
func Code ¶
Code extracts the ErrorCode from an error. Returns CodeUnknown if the error is not an AppError.
func CodeOr ¶ added in v0.3.2
CodeOr extracts err's ErrorCode like Code, but returns fallback when err carries no code (an uncoded third-party error, or nil). Use it to wrap a client error without discarding a code the client already chose.
func ContextCode ¶ added in v0.3.3
ContextCode extracts err's ErrorCode like CodeOr, but first maps an uncoded context error in the chain: context.DeadlineExceeded to CodeTimeout and context.Canceled to CodeCanceled. Use it to wrap the error of a wait that a context ended (ctx.Err(), a library's deadline error) with the code that keeps retry classification and the transport status right.
Source Files