Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( ErrBadRequest = Error{ Code: ErrorCodeBadRequest, Description: "bad request", HttpStatusCode: http.StatusBadRequest, } ErrInternalServerError = Error{ Code: ErrorCodeInternal, Description: "internal server error", HttpStatusCode: http.StatusInternalServerError, } ErrTimeout = Error{ Code: ErrorCodeTimeout, Description: "request timeout", HttpStatusCode: http.StatusInternalServerError, } ErrCanceled = Error{ Code: "ErrCanceled", Description: "client has canceled the request", HttpStatusCode: 499, } )
Predefined errors for the most common failure modes. They are meant to be used as templates and customized via the With* methods, which return copies and never mutate the shared value.
Functions ¶
This section is empty.
Types ¶
type Attributes ¶ added in v2.7.3
Attributes carries additional, structured context about an error, e.g. for logging or returning machine-readable details to the caller.
type Error ¶
type Error struct {
// Code is the stable, machine-readable error classification.
Code ErrorCode
// Description is a human-readable message safe to expose to the caller.
Description string
// Attributes holds optional structured context about the error.
Attributes Attributes
// Explicitly set the status code of the response
HttpStatusCode int
// The error that caused this error. Can be unwrapped to using Unwrap()
Cause error
}
Error is the canonical error type used across the API layer. It bundles a machine-readable Code, a human-readable Description, optional structured Attributes and an underlying Cause. It implements the error interface and supports errors.Is/As/Unwrap via Cause.
Instances are treated as immutable: the With* helpers return a modified copy rather than mutating the receiver.
func Errorf ¶ added in v2.3.27
Errorf builds an Error with the given code and a formatted description.
Any error passed as an argument is kept as the Cause (via the standard %w wrapping, but also via %s or %v) but is scrubbed from the human-readable Description so that internal details are never leaked to the caller. Depending on where the error appears in the message it is either dropped entirely (at the start or end, together with an adjacent colon and whitespace) or replaced with a "(redacted)" placeholder (in the middle).
func (Error) Error ¶
Error implements the error interface. The Cause, when present, is appended for diagnostics; do not rely on this format for client-facing output.
func (Error) Unwrap ¶ added in v2.3.58
Unwrap returns the underlying Cause, enabling errors.Is and errors.As.
func (Error) WithAttribute ¶ added in v2.7.3
WithAttribute returns a copy of e with key set to value. The receiver's Attributes map is cloned, so the original error is left unchanged.
func (Error) WithAttributes ¶ added in v2.7.3
func (e Error) WithAttributes(newValues Attributes) Error
WithAttributes returns a copy of e with newValues merged into its Attributes. Existing keys are overwritten and the original error is left unchanged.
type ErrorCode ¶ added in v2.7.3
type ErrorCode string
ErrorCode is a stable, machine-readable identifier for a class of error. Unlike the human-facing Description, it is safe for clients to switch on.
type ErrorResponse ¶
type ErrorResponse struct {
Code ErrorCode `json:"code"`
Description string `json:"description"`
Attributes Attributes `json:"attributes"`
// The status code, defaults to http.StatusInternalServerError if not set
StatusCode int `json:"-"`
}
ErrorResponse is the error returned to clients when a request fails. It mirrors the public fields of Error and additionally carries the HTTP status code to use for the response.
type ErrorResponseWrapper ¶ added in v2.7.3
type ErrorResponseWrapper struct {
Error ErrorResponse `json:"error"`
}
ErrorResponse is the JSON body returned to clients when a request fails. It wraps an ErrorResponse object.
Source Files
Directories