Stop guessing what to do with errors.
Behavioral classification, exit codes, HTTP status mapping, and diagnostic rules. One concept — Family — answers retry, exit code, HTTP status, and tone.
package main
import (
"errors"
"os"
errorfamily "github.com/LarsArtmann/go-error-family"
)
func main() {
err := errors.New("connection refused")
// Classify any error into a behavioral family
family := errorfamily.Classify(err)
// → Transient (unknown errors are retryable)
if errorfamily.IsRetryable(err) {
retry() // backoff/jitter are yours
}
os.Exit(errorfamily.ExitCode(err))
// → 75 (EX_TEMPFAIL)
}Classification that drives behavior.
One concept — Family — maps to retry decisions, exit codes, HTTP status, and user-facing tone.
Behavioral Classification
Five families (Rejection, Conflict, Transient, Corruption, Infrastructure) map to retry decisions, exit codes, HTTP status, and user-facing tone.
Universal Classify
Classify ANY error via a 6-step chain: multi-error, interface, sentinel, classifier, default. Zero allocations on the hot path.
Multi-Error Support
errors.Join with Classify picks the worst family by severity. Deterministic regardless of argument order. Fail-closed.
HTTP Middleware
HTTPHandler maps errors to safe JSON responses with correct status codes. Never leaks internal error messages.
Diagnostic Rules
Auto-discover root causes: filesystem, network, git, PostgreSQL. Structured Fix commands, not prose to parse.
Zero Dependencies
Root module has zero third-party deps. Only stdlib. Optional submodules for oops bridge and diagnostics.
Four steps from error to action.
Every error flows through this pipeline. Classify, decide, handle, diagnose.
Classify
Any error becomes a Family: interface, sentinel, classifier, or default.
family := errorfamily.Classify(err) Decide
Retry? Exit code? HTTP status? All derived from the Family.
errorfamily.IsRetryable(err) // true Handle
CLI boundary: structured What/Why/Fix/WayOut messages on stderr.
os.Exit(errorfamily.HandleError(err)) Diagnose
Auto-discover root cause: filesystem, network, git, PostgreSQL.
runner.Run(ctx, err) → []DiagnosticResult Why go-error-family?
fmt.Errorf answers none of these. A DIY approach gets half of them wrong.
| fmt.Errorf | DIY | go-error-family | |
|---|---|---|---|
| Behavioral classification | manual | ||
| Retry decisions | string match | ||
| Exit code mapping | manual | ||
| HTTP status mapping | manual | ||
| Multi-error severity | |||
| User-facing messages | manual | ||
| Diagnostic rules | |||
| Dependencies | 0 | 0 | 0 |
Built for real boundaries.
Drop it in at any program boundary — CLI, HTTP, library.
CLI Tools
Correct exit codes and user-facing messages from any error
HTTP APIs
Status codes and safe JSON responses without internal leakage
Libraries & SDKs
Classify errors at the domain boundary, let consumers decide
Classify. Decide. Handle.
One import. Zero dependencies. Every error gets a family.