How do you define a custom Go error type that carries structured fields a caller can read?

## What a typed error is In Go, `error` is an ordinary interface with a single method: ```go type error interface { Error() string } ``` A *typed* error (also called a structured or custom error) is a named type you declare yourself that satisfies that interface **and carries fields**. The message string is still there for humans, but the fields are there for code: the caller can look at `e.Field`, `e.Line` or `e.StatusCode` and branch on it instead of doing string surgery on the message. ## The declaration Three things are needed, and only three: 1. A type — almost always a struct, because you want more than one fact in it. 2. Exported fields for whatever the caller is meant to use. 3. An `Error() string` method that renders those fields into one line. ```go type FieldError struct { Field string Rule string } func (e *FieldError) Error() string { return "field " + e.Field + " violates rule " + e.Rule } ``` That is the whole contract. There is no base class to embed, nothing to register, and no interface list to declare — Go's interface satisfaction is structural, so writing the method is what makes the type an error. ## Value or pointer receiver The overwhelmingly common convention is a **pointer receiver** and a pointer at the return site: ```go return &FieldError{Field: "email", Rule: "format"} ``` With `func (e *FieldError) Error() string`, only `*FieldError` satisfies `error`; the bare `FieldError` value does not. That is a feature: there is exactly one dynamic type in play, so every caller knows what to match against, and nothing accidentally copies a large struct on every call to `Error()`. If you write the method on a value receiver instead, *both* `FieldError` and `*FieldError` satisfy `error`, and callers now have to guess which one your package actually returns. The compiler catches the mismatch immediately if you get it backwards. Returning `FieldError{...}` where the method is on `*FieldError` fails to build with a message saying the type does not implement `error` because method `Error` has a pointer receiver. ## What the message should say Go's convention is that error strings are lowercase and carry no trailing punctuation, because they are routinely concatenated: an outer layer writes `"loading user profile: "` in front of yours and the result should read as one sentence. Include the field values in the text — the message and the fields should tell the same story, so the log line is useful even where nobody inspected the type. ## How the caller uses it The caller does not type-assert blindly. It declares a variable of the pointer type and hands its address to `errors.As`, which searches the error and everything it wraps and assigns the first match: ```go var fe *FieldError if errors.As(err, &fe) { httpStatus = 422 badField = fe.Field } ``` That is why the fields are exported and why the type itself is usually exported: once a caller writes `errors.As` against it, the type name and its field names are part of your package's public API, and renaming `Field` is a breaking change exactly like renaming a function. ## Where this shape earns its keep Generated code is the clearest case. A code generator that emits Go types from a schema can emit one `FieldError` type alongside them, populated with the schema path and the rule that failed. The consumer of the generated package then gets machine-readable validation failures for free — it can build an HTTP 422 body listing every bad field — without the generator having to invent a message format and without the consumer having to parse one back. ## Common mistakes * Declaring `String() string` instead of `Error() string`. That satisfies `fmt.Stringer`, not `error`, and the compiler will reject the return. * Putting the interesting data only in the message text, so the caller has to parse it back out. If you had to write the value into a string, it should have been a field. * Hiding the fields behind unexported names with no accessors, which leaves the caller with nothing but the message again. * Mixing receivers within one type, so some methods are on `T` and `Error()` is on `*T` — legal, but it makes the method set harder to reason about for no benefit.