Retryable and Terminal Failures

## The problem: the decision is far from the failure A failure happens deep in a call stack — a socket write, a query, a serialization step. The decision about whether to try again is made near the top, in a worker loop or a request handler. Everything in between only forwards the error, usually wrapping it for context. So whatever encodes "this may work next time" has to be **inside the error value**, and it has to survive being wrapped. That single requirement rules out the two approaches people reach for first. - **A second return value** — `func Do() (Result, error, bool)` or an `ErrRetryable bool` field on some result struct. The first intermediate caller that does `if err != nil { return fmt.Errorf("loading user: %w", err) }` has nowhere to put the bool, and it is gone. - **Message text** — `strings.Contains(err.Error(), "timeout")`. `Error()` output is prose for humans. No package promises its stability, wrapping prefixes it, and the same word appears in errors that mean something else. ## Shape one: an exported sentinel ```go var ErrTemporary = errors.New("temporary failure") func (c *Client) Fetch(ctx context.Context, id string) ([]byte, error) { b, err := c.do(ctx, id) if err != nil { return nil, fmt.Errorf("fetch %s: %w", id, ErrTemporary) } return b, nil } ``` The caller writes `if errors.Is(err, ErrTemporary)`. `errors.Is` walks the `Unwrap` chain, so any number of intermediate `%w` wraps are transparent. The sentinel is cheap and unambiguous, but it is a single bit: it says "retryable" and nothing about which operation failed, how long to wait, or whether the request actually reached the other side. Note the `%w` verb specifically. `%v` formats the error into the message and breaks the chain; `%w` keeps the wrapped error reachable by `errors.Is` and `errors.As`. Getting this wrong is the single most common reason a classification silently stops working after a refactor. ## Shape two: a behavioural method ```go type TransientError struct { Op string Err error } func (e *TransientError) Error() string { return e.Op + ": " + e.Err.Error() } func (e *TransientError) Unwrap() error { return e.Err } func (e *TransientError) Retryable() bool { return true } ``` The caller does not need to import the type at all: ```go var r interface{ Retryable() bool } if errors.As(err, &r) && r.Retryable() { // another attempt is permitted } ``` `errors.As` accepts a pointer to an interface type as its target, and assigns the first error in the chain that implements it. That is what makes this shape composable: three different packages can each define their own error type with a `Retryable() bool` method, and one classification function in the worker handles all of them without importing any of them. This is the standard library's own pattern — network errors expose `Timeout() bool` through the `net.Error` interface, and callers routinely match the behaviour rather than the concrete type. The library also carries a warning: an older `Temporary() bool` method on that interface was deprecated precisely because "temporary" was never given a definition anyone agreed on. If you export a `Retryable() bool`, document exactly what it promises — most usefully, whether the operation might have been applied on the other side. ## Carrying more than a bit The typed form's real advantage is that it can carry the facts the retry decision actually needs: ```go type SendError struct { Op string Sent bool // did the request leave the process? RetryAfter time.Duration // if the peer told us Err error } ``` `Sent` matters because a retry of a non-idempotent operation is only safe if you know the first attempt never happened. A sentinel cannot express that; a typed error can, and the caller extracts it with `errors.As(err, &se)` into a `*SendError`. ## Both shapes are API Once exported, either shape is a compatibility promise. Callers write `errors.Is(err, ErrTemporary)` or `Retryable()` checks against it, and if a later release stops setting it — even for a good reason — every consumer's retry loop silently changes behaviour with no compile error. Choose deliberately, document the meaning, and prefer exporting facts about what happened over exporting a verdict about what the caller should do. ## What an interviewer is listening for That you name wrapping as the reason the classification must live in the value; that you can write both the sentinel and the behavioural-interface check correctly, including `%w` and the pointer-to-interface target for `errors.As`; and that you notice this becomes part of the package's public contract.