Summary

No distinction between "I did something wrong" and "Google API is down". All errors look the same.

Current State

All errors are returned identically regardless of cause:

• Invalid input (user's fault)
• API rate limiting (temporary)
• Network failure (system issue)
• Authentication expired (fixable)

Problems

1. Users cannot easily distinguish between actionable and non-actionable errors
2. No guidance on what to do next
3. Retryable errors treated same as permanent failures

Proposed Solution

Create error types:

type UserError struct {
    Message string
}

func (e UserError) Error() string { return e.Message }

type SystemError struct {
    Message   string
    Cause     error
    Retryable bool
}

func (e SystemError) Error() string { return e.Message }

Commands can then provide different guidance:

if errors.As(err, &userErr) {
    fmt.Fprintf(os.Stderr, "Error: %s\n", userErr.Message)
} else if errors.As(err, &sysErr) {
    fmt.Fprintf(os.Stderr, "System error: %s\n", sysErr.Message)
    if sysErr.Retryable {
        fmt.Fprintf(os.Stderr, "This may be temporary. Try again later.\n")
    }
}

Priority

P2 - Improves user experience