Retracted: v0.1.x carried one consumer's product code and configuration; 0.2.0 is the first
product-agnostic release. Upgrade to v0.2.0 or later (see CHANGELOG.md).
Documentation
¶
Overview ¶
Package errors provides application error types and codes.
Index ¶
- Constants
- Variables
- func As(err error, target any) bool
- 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" // 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 ¶
var ( // Combine merges multiple errors into a single error. nil errors are // discarded. If all errors are nil, returns nil. Combine = multierr.Combine // Append appends right into left, returning the combined error. Either // value may be nil, in which case the other is returned unchanged. Append = multierr.Append )
Multierr re-exports for convenience.
Functions ¶
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 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).
func IsTransient ¶
IsTransient returns true if the error represents a transient failure that may succeed on retry (timeout, unavailable, certain internal errors).
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.
Source Files