Gogoerror-handlingapistructured-errorsproduction-ready
Structured Custom Errors
Production error handling patterns with sentinel errors, wrapped context, error types, and structured error responses for APIs.
package apperror
import (
"errors"
"fmt"
"net/http"
"runtime"
)
// Sentinel errors for comparison with errors.Is()
var (
ErrNotFound = errors.New("resource not found")
ErrUnauthorized = errors.New("unauthorized")
ErrForbidden = errors.New("forbidden")
ErrConflict = errors.New("resource conflict")
ErrValidation = errors.New("validation error")
ErrInternal = errors.New("internal error")
ErrRateLimit = errors.New("rate limit exceeded")
)
// AppError provides structured error information for API responses
type AppError struct {
Code string // Machine-readable error code
Message string // Human-readable message
StatusCode int // HTTP status code
Cause error // Underlying error (wrapped)
Fields map[string]string // Validation field errors
RequestID string // For correlation
Stack string // Call stack for debugging
}
func (e *AppError) Error() string {
if e.Cause != nil {
return fmt.Sprintf("%s: %v", e.Message, e.Cause)
}
return e.Message
}
func (e *AppError) Unwrap() error {
return e.Cause
}
// Is supports errors.Is() by checking the Cause chain
func (e *AppError) Is(target error) bool {
return errors.Is(e.Cause, target)
}
// Builder pattern for constructing errors
func New(code string, message string) *AppError {
return &AppError{
Code: code,
Message: message,
StatusCode: http.StatusInternalServerError,
Stack: captureStack(2),
}
}
func (e *AppError) WithStatus(status int) *AppError {
e.StatusCode = status
return e
}
func (e *AppError) WithCause(err error) *AppError {
e.Cause = err
return e
}
func (e *AppError) WithFields(fields map[string]string) *AppError {
e.Fields = fields
return e
}
func (e *AppError) WithRequestID(id string) *AppError {
e.RequestID = id
return e
}
// Convenience constructors
func NotFound(resource string, id string) *AppError {
return New("NOT_FOUND", fmt.Sprintf("%s with id '%s' not found", resource, id)).
WithStatus(http.StatusNotFound).
WithCause(ErrNotFound)
}
func Unauthorized(reason string) *AppError {
return New("UNAUTHORIZED", reason).
WithStatus(http.StatusUnauthorized).
WithCause(ErrUnauthorized)
}
func Forbidden(reason string) *AppError {
return New("FORBIDDEN", reason).
WithStatus(http.StatusForbidden).
WithCause(ErrForbidden)
}
func ValidationFailed(fields map[string]string) *AppError {
return New("VALIDATION_ERROR", "Request validation failed").
WithStatus(http.StatusBadRequest).
WithCause(ErrValidation).
WithFields(fields)
}
func Internal(err error) *AppError {
return New("INTERNAL_ERROR", "An internal error occurred").
WithStatus(http.StatusInternalServerError).
WithCause(fmt.Errorf("%w: %v", ErrInternal, err))
}
// ToHTTPResponse converts the error to a JSON-serializable response
type ErrorResponse struct {
Error struct {
Code string `json:"code"`
Message string `json:"message"`
Fields map[string]string `json:"fields,omitempty"`
RequestID string `json:"request_id,omitempty"`
} `json:"error"`
}
func (e *AppError) ToResponse() ErrorResponse {
resp := ErrorResponse{}
resp.Error.Code = e.Code
resp.Error.Message = e.Message
resp.Error.Fields = e.Fields
resp.Error.RequestID = e.RequestID
return resp
}
func captureStack(skip int) string {
buf := make([]byte, 4096)
n := runtime.Stack(buf, false)
return string(buf[:n])
}
// HandleError is a helper for HTTP handlers
func HandleError(w http.ResponseWriter, err error) {
var appErr *AppError
if errors.As(err, &appErr) {
writeJSON(w, appErr.StatusCode, appErr.ToResponse())
return
}
// Unknown error - wrap as internal
internal := Internal(err)
writeJSON(w, internal.StatusCode, internal.ToResponse())
}title: "Structured Custom Errors" description: "Production error handling patterns with sentinel errors, wrapped context, error types, and structured error responses for APIs." category: "Go" language: "go" tags: ["go", "error-handling", "api", "structured-errors", "production-ready"] createdAt: "2025-02-25" updatedAt: "2025-03-15"
Overview
A structured error system that provides machine-readable codes, HTTP status mapping, field-level validation errors, and proper error wrapping. Supports Go's errors.Is() and errors.As() for programmatic error inspection throughout the call stack.
Code
err := apperror.NotFound("user", "usr_123")
err = apperror.ValidationFailed(map[string]string{
"email": "invalid format",
})
apperror.HandleError(w, err)Notes
- Sentinel errors enable
errors.Is()checks without inspecting strings - The builder pattern allows attaching context incrementally as errors propagate up
Unwrap()implementation enables the standard library's error chain traversal- Stack capture at creation time pinpoints where errors originate (expensive, use in non-hot paths)
HandleErrorconverts any error into a consistent JSON response format