
Any type that implements `Error() string` satisfies the `error` interface. A custom error struct lets you attach structured context - HTTP status codes, resource IDs, error codes - that callers extract with `errors.As` without parsing strings.

<ExamplePair>
<ExampleProse>

Define a struct with the fields you need, implement `Error() string`, and return the concrete type as an `error` interface from public APIs.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "errors"
    "fmt"
)

type RequestError struct {
    StatusCode int
    Method     string
    URL        string
}

func (e *RequestError) Error() string {
    return fmt.Sprintf("%s %s: status %d", e.Method, e.URL, e.StatusCode)
}

func fetchData(url string) error {
    // simulated HTTP call returning 404
    return &RequestError{
        StatusCode: 404,
        Method:     "GET",
        URL:        url,
    }
}

func main() {
    err := fetchData("/api/users/99")
    if err != nil {
        fmt.Println(err)

        var re *RequestError
        if errors.As(err, &re) {
            fmt.Printf("HTTP %d on %s %s\n", re.StatusCode, re.Method, re.URL)
        }
    }
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

You can also implement `Unwrap() error` to participate in error chain inspection:

</ExampleProse>
<ExampleCode>

```go
type DBError struct {
    Op  string
    Err error // underlying cause
}

func (e *DBError) Error() string  { return fmt.Sprintf("db %s: %v", e.Op, e.Err) }
func (e *DBError) Unwrap() error  { return e.Err }

var ErrConnFailed = errors.New("connection failed")

err := &DBError{Op: "query", Err: ErrConnFailed}
fmt.Println(errors.Is(err, ErrConnFailed)) // true - Unwrap lets Is walk the chain
```

</ExampleCode>
</ExamplePair>

<InProduction>
Return the concrete error type as an `error` interface from public functions - returning `*RequestError` directly leaks implementation details and breaks `errors.As` chains when callers use the interface. A custom error type lets callers extract structured context (HTTP status, error code, resource ID) without string parsing. Accept `error` in function signatures, not concrete types; code that receives an `error` is decoupled from the specific implementation. Implement `Unwrap() error` when your custom error wraps another error so `errors.Is` and `errors.As` can traverse the full chain.
</InProduction>


Implementing the error interface with a struct to carry structured context callers can extract.

Custom Errors


A goroutine is a function executing concurrently with other goroutines in the same address space. The `go` keyword launches one. Goroutines start with a small stack (around 2-8 KB) that grows as needed, so spawning thousands is practical.

<ExamplePair>
<ExampleProse>

Prefix any function call with `go` to run it concurrently. The calling goroutine continues immediately without waiting. If `main` returns before the goroutine finishes, the goroutine is killed.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "time"
)

func say(s string) {
    for i := 0; i < 3; i++ {
        time.Sleep(50 * time.Millisecond)
        fmt.Println(s)
    }
}

func main() {
    go say("goroutine") // runs concurrently
    say("main")         // runs in the main goroutine
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Anonymous functions work too - useful for short, in-place concurrent tasks:

</ExampleProse>
<ExampleCode>

```go
go func(msg string) {
    fmt.Println(msg)
}("hello from goroutine")
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

The goroutine scheduler is co-operative with preemption points at function calls, channel operations, and system calls. GOMAXPROCS (default: number of CPU cores) controls how many goroutines run in parallel on OS threads. Use a channel or `sync.WaitGroup` to wait for goroutines to finish:

</ExampleProse>
<ExampleCode>

```go
done := make(chan struct{})
go func() {
    fmt.Println("working...")
    close(done)
}()
<-done // blocks until goroutine closes the channel
```

</ExampleCode>
</ExamplePair>

<InProduction>
Goroutines are cheap but not free. Launching one per inbound request in a high-QPS service can create millions of live goroutines under load, each holding a stack frame while blocked on I/O. Use a worker pool or semaphore to bound concurrency when processing untrusted input or calling rate-limited services. The main goroutine exiting kills all goroutines immediately - use `sync.WaitGroup` or a done channel to ensure cleanup runs before exit.
</InProduction>


Lightweight concurrent functions launched with the go keyword - the foundation of Go's concurrency model.

Goroutines


In Go, errors are values returned from functions - not thrown exceptions. A function that can fail returns `(result, error)` and callers decide what to do at each call site.

<ExamplePair>
<ExampleProse>

`errors.New` creates a simple error with a static message. `fmt.Errorf` creates an error with a formatted message and, when you use `%w`, wraps another error so callers can inspect the chain.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "errors"
    "fmt"
)

var ErrNotFound = errors.New("not found")

func findUser(id int) (string, error) {
    if id != 1 {
        return "", fmt.Errorf("findUser %d: %w", id, ErrNotFound)
    }
    return "alice", nil
}

func main() {
    name, err := findUser(2)
    if err != nil {
        fmt.Println("error:", err)

        if errors.Is(err, ErrNotFound) {
            fmt.Println("user does not exist")
        }
        return
    }
    fmt.Println("found:", name)
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`errors.Is` walks the entire error chain looking for a match, so it works even when the sentinel is wrapped several levels deep:

</ExampleProse>
<ExampleCode>

```go
// wrapping three levels deep
err := fmt.Errorf("layer3: %w", fmt.Errorf("layer2: %w", ErrNotFound))
fmt.Println(errors.Is(err, ErrNotFound)) // true
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`errors.As` extracts a typed error from the chain - useful when the error carries structured fields:

</ExampleProse>
<ExampleCode>

```go
type ValidationError struct {
    Field string
    Msg   string
}

func (e *ValidationError) Error() string {
    return fmt.Sprintf("validation: %s %s", e.Field, e.Msg)
}

func validate(age int) error {
    if age < 0 {
        return &ValidationError{Field: "age", Msg: "must be non-negative"}
    }
    return nil
}

err := validate(-1)
var ve *ValidationError
if errors.As(err, &ve) {
    fmt.Println("field:", ve.Field) // field: age
}
```

</ExampleCode>
</ExamplePair>

<InProduction>
Wrap errors with `%w` to create an inspectable chain - callers use `errors.Is` / `errors.As` without string matching. Use sentinel errors (`var ErrNotFound = errors.New(...)`) for expected conditions callers must handle explicitly; use wrapped errors for unexpected conditions that need context. Never swallow errors silently - at minimum log them. `if err != nil { return err }` is idiomatic Go error propagation; it is a deliberate design choice to make every failure path explicit.
</InProduction>


errors.New, fmt.Errorf with %w, errors.Is, errors.As, and sentinel errors - Go errors are values.