Error Handling

func NewNotFound(resource, id string) *AppError {
    return &AppError{Code: "NOT_FOUND", Message: fmt.Sprintf("%s with id %s not found", resource, id), HTTPStatus: 404}
}

func NewBadRequest(message string) *AppError {
    return &AppError{Code: "BAD_REQUEST", Message: message, HTTPStatus: 400}
}

func NewInternal(cause error) *AppError {
    return &AppError{Code: "INTERNAL_ERROR", Message: "an internal error occurred", HTTPStatus: 500, cause: cause}
}

func NewUnauthorized(message string) *AppError {
    return &AppError{Code: "UNAUTHORIZED", Message: message, HTTPStatus: 401}
}

func NewConflict(message string) *AppError {
    return &AppError{Code: "CONFLICT", Message: message, HTTPStatus: 409}
}

// Wrap attaches a cause to an AppError, returning a new instance (immutable).
func Wrap(appErr *AppError, cause error) *AppError {
    return &AppError{Code: appErr.Code, Message: appErr.Message, HTTPStatus: appErr.HTTPStatus, cause: cause}
}

Error Wrapping with fmt.Errorf

Add context at every layer boundary using %w:

// Repository layer
func (r *Repo) FindByID(ctx context.Context, id uuid.UUID) (*model.Order, error) {
    if err := row.Scan(&order); err != nil {
        return nil, fmt.Errorf("querying order %s: %w", id, err)
    }
    return &order, nil
}

// Application layer
order, err := h.repo.FindByID(ctx, id)
if err != nil { return nil, fmt.Errorf("getting order for display: %w", err) }

Sentinel Errors

// internal/domain/model/errors.go
var (
    ErrInsufficientStock = errors.New("insufficient stock for requested quantity")
    ErrAlreadyCompleted  = errors.New("entity is already in completed state")
    ErrInvalidTransition = errors.New("invalid state transition")
)

Checking:

if errors.Is(err, model.ErrInsufficientStock) {
    return apperror.NewBadRequest("not enough stock available")
}

var appErr *apperror.AppError
if errors.As(err, &appErr) {
    log.Printf("app error: code=%s status=%d", appErr.Code, appErr.HTTPStatus)
}

Error-to-HTTP Mapping Middleware

type ErrorResponse struct {
    Error struct { Code string `json:"code"`; Message string `json:"message"` } `json:"error"`
}

func ErrorHandler(logger *zap.Logger, handler func(w http.ResponseWriter, r *http.Request) error) http.HandlerFunc {
    return func(w http.ResponseWriter, r *http.Request) {
        if err := handler(w, r); err == nil { return } else {
            var appErr *apperror.AppError
            if !errors.As(err, &appErr) { appErr = apperror.NewInternal(err) }
            if appErr.HTTPStatus >= 500 {
                logger.Error("internal error", zap.Error(err), zap.String("code", appErr.Code))
            } else {
                logger.Warn("client error", zap.String("code", appErr.Code))
            }
            w.Header().Set("Content-Type", "application/x-msgpack")
            w.WriteHeader(appErr.HTTPStatus)
            resp := ErrorResponse{}
            resp.Error.Code = appErr.Code; resp.Error.Message = appErr.Message
            _ = msgpack.NewEncoder(w).Encode(resp)
        }
    }
}

Error Catalog Pattern

Centralize all domain-specific errors per service:

var (
    ErrOrderNotFound   = apperror.NewNotFound("order", "")
    ErrDuplicateOrder  = apperror.NewConflict("order with this reference already exists")
    ErrInvalidQuantity = apperror.NewBadRequest("quantity must be greater than zero")
)
// Usage: return apperror.Wrap(errors.ErrOrderNotFound, fmt.Errorf("id: %s", id))

Error Logging Rules

Never log: passwords, tokens, PII, full request bodies with sensitive data.

JetStream Request-Reply Error Responses

For JetStream-based request-reply (inter-service queries), error responses use the same AppError envelope serialized as MsgPack (NOT JSON). The responder publishes the error response to the reply subject extracted from the incoming message's msg.Reply (core NATS auto-set) header. nc.Publish() is FORBIDDEN — use nc.Request() for RPC or js.PublishMsg() for events -- use js.PublishMsg to the reply subject instead.

// JetStream reply with AppError envelope -- publish to reply subject (MsgPack-encoded)
func replyWithError(ctx context.Context, js nats.JetStreamContext, msg *nats.Msg, appErr *AppError) error {
    replySubject := msg.Header.Get("msg.Reply (core NATS auto-set)")
    if replySubject == "" {
        return fmt.Errorf("no msg.Reply (core NATS auto-set) header in message")
    }

    resp := ErrorResponse{}
    resp.Error.Code = appErr.Code
    resp.Error.Message = appErr.Message
    data, _ := msgpack.Marshal(resp) // MsgPack for all NATS inter-service payloads

    replyMsg := &nats.Msg{
        Subject: replySubject,
        Data:    data,
        Header:  nats.Header{},
    }
    replyMsg.Header.Set("X-Error-Code", appErr.Code)
    replyMsg.Header.Set("X-Error-Status", fmt.Sprintf("%d", appErr.HTTPStatus))

    // Publish reply via JetStream (NOT msg.Respond which uses core NATS)
    _, err := js.PublishMsg(replyMsg)
    return err
}

// Client-side: detect error in JetStream reply (received via core NATS request-reply)
func checkReplyError(reply *nats.Msg) error {
    if errCode := reply.Header.Get("X-Error-Code"); errCode != "" {
        status, _ := strconv.Atoi(reply.Header.Get("X-Error-Status"))
        return &AppError{
            Code:       errCode,
            Message:    string(reply.Data),
            HTTPStatus: status,
        }
    }
    return nil
}

Request-Reply Timeout Handling with Circuit Breaker

// Using core NATS request-reply (JetStream-based request-reply, NOT core NATS nc.Request)
reply, err := replyRouter.Request(ctx, subject, data, headers, 5*time.Second)
if errors.Is(err, context.DeadlineExceeded) {
    // Record failure in circuit breaker
    cb.RecordFailure(subject)
    return nil, fmt.Errorf("service %s unavailable (timeout): %w", subject, err)
}

Common Mistakes

1. Returning raw errors to clients -- Always map to AppError before the HTTP boundary (API Gateway) or NATS reply boundary (domain services).
2. Swallowing errors -- Every if err != nil must return, log, or handle explicitly.
3. Logging and returning same error -- Log at the boundary (middleware), return elsewhere.
4. String matching instead of errors.Is -- Use errors.Is/errors.As, never compare .Error().
5. Exposing internal messages in 500s -- NewInternal uses a generic message deliberately.
6. Not handling JetStream request-reply timeouts -- JetStream request-reply (via core NATS request-reply) can time out if the responder service is down. Handle context.DeadlineExceeded with circuit breaker patterns to prevent cascading failures.
7. Using msg.Respond for error replies -- msg.Respond uses core NATS which is FORBIDDEN. Error replies must be published via js.PublishMsg to the msg.Reply (core NATS auto-set) header extracted from the incoming message.