Documentation
¶
Overview ¶
Package httperr provides HTTP-aware error types for JSON APIs.
HTTPError ¶
HTTPError carries an HTTP status code and an application error code (e.g. BAD_REQUEST, NOT_FOUND). Use New to build a custom error from an underlying error, status, and code. IsExpected is true for 4xx so callers can avoid logging them as server errors. Implementations of error, HTTPStatus, and GetCode allow handlers to respond with the correct status and JSON body.
Status-to-code mapping ¶
CodeFromStatus returns a default application code for a given HTTP status (e.g. 404 -> "NOT_FOUND"). Use it when rendering errors that do not implement the status/code interface.
Validation errors ¶
NewValidationErrorf builds an HTTPError with status 400 and code VALIDATION_ERROR for dynamic messages. For "valid JSON but business validation failed" use ErrUnprocessableEntity (422) instead.
Sentinel errors ¶
ErrInvalidID, ErrNotAuthenticated, ErrForbidden, ErrNotFound, ErrConflict, ErrGone, ErrUnprocessableEntity, ErrTooManyRequests, and ErrServiceUnavailable return ready-made *HTTPError for common cases. IsExpectedClientError reports whether an error is a 4xx client error.
Index ¶
- Variables
- func CodeFromStatus(status int) string
- func IsExpectedClientError(err error) bool
- type HTTPError
- func ErrConflict() *HTTPError
- func ErrForbidden() *HTTPError
- func ErrGone() *HTTPError
- func ErrInvalidID() *HTTPError
- func ErrNotAuthenticated() *HTTPError
- func ErrNotFound() *HTTPError
- func ErrServiceUnavailable() *HTTPError
- func ErrTooManyRequests() *HTTPError
- func ErrUnprocessableEntity() *HTTPError
- func New(err error, status int, code string) *HTTPError
- func NewValidationErrorf(format string, args ...any) *HTTPError
Constants ¶
This section is empty.
Variables ¶
var ( ErrInvalidIDSentinel = errors.New("invalid ID") ErrNotAuthenticatedSentinel = errors.New("not authenticated") ErrForbiddenSentinel = errors.New("forbidden") ErrNotFoundSentinel = errors.New("not found") ErrConflictSentinel = errors.New("conflict") ErrGoneSentinel = errors.New("gone") ErrUnprocessableEntitySentinel = errors.New("unprocessable entity") ErrTooManyRequestsSentinel = errors.New("too many requests") )
Sentinel error values used as HTTPError.Unwrap() targets by the Err* functions below.
Functions ¶
func CodeFromStatus ¶ added in v0.1.1
CodeFromStatus returns the default application error code for the given HTTP status (e.g. 404 -> "NOT_FOUND", 500 -> "INTERNAL_ERROR").
func IsExpectedClientError ¶ added in v0.1.2
IsExpectedClientError reports whether err is an HTTPError with status 4xx (client error).
Types ¶
type HTTPError ¶
type HTTPError struct {
// contains filtered or unexported fields
}
HTTPError is an error that carries HTTP status and application error code for JSON responses.
func ErrConflict ¶ added in v0.1.3
func ErrConflict() *HTTPError
ErrConflict returns an HTTPError with status 409 and code CONFLICT.
func ErrForbidden ¶ added in v0.1.3
func ErrForbidden() *HTTPError
ErrForbidden returns an HTTPError with status 403 and code FORBIDDEN.
func ErrGone ¶ added in v0.1.3
func ErrGone() *HTTPError
ErrGone returns an HTTPError with status 410 and code GONE.
func ErrInvalidID ¶
func ErrInvalidID() *HTTPError
ErrInvalidID returns an HTTPError with status 400 and code INVALID_ID.
func ErrNotAuthenticated ¶
func ErrNotAuthenticated() *HTTPError
ErrNotAuthenticated returns an HTTPError with status 401 and code NOT_AUTHENTICATED.
func ErrNotFound ¶ added in v0.1.3
func ErrNotFound() *HTTPError
ErrNotFound returns an HTTPError with status 404 and code NOT_FOUND.
func ErrServiceUnavailable ¶ added in v0.1.3
func ErrServiceUnavailable() *HTTPError
ErrServiceUnavailable returns an HTTPError with status 503 and code SERVICE_UNAVAILABLE.
func ErrTooManyRequests ¶ added in v0.1.3
func ErrTooManyRequests() *HTTPError
ErrTooManyRequests returns an HTTPError with status 429 and code RATE_LIMIT_EXCEEDED.
func ErrUnprocessableEntity ¶ added in v0.1.3
func ErrUnprocessableEntity() *HTTPError
ErrUnprocessableEntity returns an HTTPError with status 422 and code VALIDATION_ERROR.
func New ¶
New builds an HTTPError with the given underlying error, HTTP status, and application code. IsClientError is set to true when status is 4xx.
func NewValidationErrorf ¶
NewValidationErrorf creates an HTTPError with status 400 and code VALIDATION_ERROR for dynamic validation messages. For semantic "request body valid JSON but business validation failed" use ErrUnprocessableEntity (422) from sentinels.
func (*HTTPError) GetCode ¶ added in v0.1.1
GetCode returns the application error code for the JSON body.
func (*HTTPError) HTTPStatus ¶
HTTPStatus returns the HTTP status code to send in the response.
func (*HTTPError) IsClientError ¶ added in v0.2.0
IsClientError reports whether this error represents a client error (4xx).
Source Files