Стратегия уровней

Нижний уровень — сентинелы

Пакет, работающий с хранилищем, определяет эталоны своих сбоев и возвращает их напрямую:

var ErrNotFound = errors.New("файл не найден")

func Get(id string) (FileMeta, error) {
    // ...
    return FileMeta{}, ErrNotFound
}

Здесь ещё нет контекста: пакет не знает, кто и зачем его вызывает.

Средний уровень — оборачивание

Сервисный слой добавляет контекст, не теряя причину:

f, err := repo.Get(id)
if err != nil {
    return fmt.Errorf("получить файл %s: %w", id, err)
}

Каждый уровень дописывает свой кусок: «получить файл report.pdf: запрос к хранилищу: файл не найден». Итоговая строка — читаемая история пути ошибки снизу вверх.

Верхний уровень — различение

HTTP-обработчик решает, что ответить, по причине:

f, err := svc.GetFile(id)
if err != nil {
    if errors.Is(err, repo.ErrNotFound) {
        w.WriteHeader(http.StatusNotFound)
        return
    }
    w.WriteHeader(http.StatusInternalServerError)
    return
}

Обработчик не парсит текст ошибки — он использует Is/As по цепочке. Это и есть стратегия: внизу создают и возвращают, в середине оборачивают, наверху различают.

Границы между уровнями не жёсткие: оборачивание уместно и на нижнем уровне — например, вокруг сентинела драйвера БД или ошибки внешней библиотеки. Схема — удобный ориентир, а не правило, за нарушение которого полагается выговор.