Why should an exported Go function declare its result as error rather than *ValidationError?

## The rule An exported Go function that can fail declares its last result as the built-in interface type `error`: ``` func Check(env string) error ``` not as the concrete type it happens to construct today: ``` func Check(env string) *ValidationError // don't ``` This holds even when the function can only ever fail one way, and even when the concrete type is exported and documented. ## The trap that makes it a hard rule `error` is an interface: one method, `Error() string`. An interface value is a pair — a dynamic type and a value — and it is equal to `nil` only when both halves are unset. Assigning a nil `*ValidationError` into an `error` fills in the type half, so the resulting interface value is **not** nil. That is fatal at an API boundary, because callers do not read your body; they read your signature and write the universal check: ``` if err := pkg.Check(env); err != nil { return err } ``` If `Check` is declared to return `*ValidationError`, the caller who stores that result in an `error` variable — which is what happens the moment they forward it, wrap it, put it in a slice, or return it from their own function — sees a non-nil error on a perfectly successful call. The failure is silent, it is on the *happy* path, and it usually surfaces far away from the package that caused it. Declaring the result as `error` removes the possibility: the function returns a literal `nil` on success, the interface is genuinely empty, and the caller's check works. ## The contractual reason Even without the trap, a concrete result type over-promises. The signature is the promise other teams compile against: - **`error` says "this call can fail" and nothing more.** You may later return a sentinel value, an error built by `fmt.Errorf`, a joined set of errors, or a different struct entirely, and no caller's code changes. - **A concrete type says "failures are always exactly this".** Widening it later means editing the signature, which is an incompatible change for everyone who wrote `var e *ValidationError = pkg.Check(...)`. - **Callers who need the detail still have it.** `errors.As` will find a `*ValidationError` anywhere in the chain, and a documented, exported error type plus `errors.As` in the doc comment is the idiomatic way to offer detail without pinning the signature. ## Where the concrete type is fine Inside the package. An unexported helper may return `*ValidationError` so the code that builds and inspects it stays typed; the exported wrapper converts to `error` at the boundary. The dangerous move is the one that looks harmless — returning that helper's result directly from a function declared to return `error` while the helper's own signature is concrete, because the nil case is exactly where the typed value slips into the interface. The safe shape is an explicit `return nil` on the success path of the exported function. ## What this looks like in review Three things a reviewer checks on any exported signature: 1. The failure result is spelled `error`. 2. The success path returns a literal `nil`, not a variable of a concrete pointer type. 3. If callers need to distinguish failures, the doc comment says which exported error types or sentinel values they can look for, so nobody has to string-match the message. ## Why interviewers ask It is a single-line signature decision whose consequences land in someone else's codebase, which makes it a good probe for whether a candidate designs for callers rather than for the function body. A candidate who says "return `error` because interfaces are more flexible" has half of it; the other half — that a concrete pointer result can make a caller's `err != nil` fire on success — is the part that turns a preference into a rule.