go-error-handling

To wrap errors in Go without duplicate logs, follow the log-or-return rule: wrap the error with %w for context, return it once, and let the top-level handler decide whether to log or translate it.

Choosing between sentinel, typed, and opaque errors in Go depends on how callers need to react: use opaque errors when callers only log, sentinel for specific checks with errors.Is, and typed for extracting structured data with errors.As.

Inspect wrapped errors in Go using errors.Is to check for specific sentinel values and errors.As to extract typed error structures, avoiding fragile string matching while preserving error identity through the %w wrapping verb.

Use errors.Join in Go when you need to combine multiple independent errors into a single error value, whereas %w is for adding contextual information to a single underlying error during propagation.

Go error handling breaks API boundaries when internal errors leak through opaque returns or string matching. Preserve API stability by selecting appropriate error strategies and using errors.Is and errors.As for safe inspection.

You can migrate Go functions to joined error strategies by analyzing boundary layers, applying errors.Join for multiple failures, and using single-point logging to maintain debuggability and API stability.