Error Handling Scenario

The scenario with the wrapping chain:

func processOrder(orderID string) error {
    user, err := loadUser(orderID)
    if err != nil {
        return fmt.Errorf("process order %s: load user: %w", orderID, err)  // layer 1 context
    }

    charge, err := chargePayment(orderID, user)
    if err != nil {
        // payment failed — decide the ACTION, not just the return
        if isRetryable(err) {
            return fmt.Errorf("process order %s: charge: %w", orderID, err)  // upstream retries
        }
        return fmt.Errorf("process order %s: charge: %w", orderID, err)  // no retry for card declined
    }

    if err := publishQueue(orderID); err != nil {
        log.Printf("queue publish failed for %s (non-fatal): %v", orderID, err)
        // Queue failure: the ORDER is processed — don't fail the whole flow
        // (outbox pattern: record locally, retry later)
    }
    return nil
}

The decisions in this scenario:

1. 1
   EACH layer wraps with ITS context (the order ID, the operation) — %w everywhere
2. 2
   The caller sees the full chain: 'process order 123: charge: connection refused'
3. 3
   Retryable vs terminal — checked and acted on at the layer with the knowledge
4. 4
   Queue failure — the business outcome succeeded (payment charged); the notification is eventually-consistent (log + outbox), not a hard fail

The errors.As pattern at the top: if the API layer needs the specific error type: var apiErr APIError if errors.As(err, &apiErr) { if apiErr.Code == 429 { / backoff */ } }

The anti-pattern: wrapping everything as a generic 'something failed' — every layer adding context but nobody adding facts.