Паттерны обработки ошибок в Go API для понятных и единообразных ответов

Почему несогласованные ошибки API раздражают клиентов

Когда каждый эндпоинт сообщает об ошибках по‑разному, клиенты перестают доверять вашему API. Один маршрут возвращает { \"error\": \"not found\" }, другой — { \"message\": \"missing\" }, а третий шлёт простой текст. Даже если смысл близок, клиентский код теперь вынужден угадывать, что произошло.

Цена проявляется быстро. Команды пишут хрупкую логику парсинга и добавляют специальные случаи под каждый эндпоинт. Повторы становятся рискованными, потому что клиент не может отличить «повторить позже» от «исправьте ввод». Количество запросов в поддержку растёт, потому что клиент видит расплывчатое сообщение, и ваша команда не может легко сопоставить его с записью в логе сервера.

Типичный сценарий: мобильное приложение вызывает три эндпоинта при регистрации. Первый возвращает HTTP 400 с картой ошибок по полям, второй отдаёт HTTP 500 со стектрэйсом, а третий возвращает HTTP 200 с { \"ok\": false }. Команда приложения выпускает три разных обработчика ошибок, а бэкенд‑команда продолжает получать отчёты вроде «регистрация иногда падает» без ясной точки старта.

Цель — один предсказуемый контракт. Клиенты должны надежно понимать, кто виноват (они или вы), стоит ли пробовать повтор и есть ли у них идентификатор запроса, который можно вставить в обращение в поддержку.

Примечание по области: это руководство про JSON HTTP API (не про gRPC), но те же идеи применимы везде, где вы возвращаете ошибки другим системам.

Простая цель: один контракт, которому подчиняются все эндпоинты

Выберите один понятный контракт для ошибок и заставьте все эндпоинты ему следовать. «Согласованность» означает одинаковую форму JSON, одинаковое значение полей и одинаковое поведение вне зависимости от того, какой обработчик упал. Как только это сделано, клиенты перестают угадывать и начинают корректно обрабатывать ошибки.

Полезный контракт помогает клиенту решить, что делать дальше. Для большинства приложений каждый ответ с ошибкой должен отвечать на три вопроса:

• Могу ли я исправить ввод?
• Стоит ли повторить позже?
• Нужна ли поддержка (контакт)?

Практический набор правил:

• Одна схема ответа для всех ошибок.
• Одна политика статус‑кодов (каждому типу ошибки всегда соответствует один и тот же HTTP-статус).
• Одна политика безопасных сообщений (что можно показывать пользователю, а что остаётся внутренним).
• Один механизм корреляции (request ID в ответе, чтобы поддержка могла найти отказ).

Решите заранее, что никогда не должно появляться в ответах. Часто это: фрагменты SQL, трассировки стека, внутренние хостнеймы, секреты и сырые строки ошибок от зависимостей.

Держите чистое разделение: короткое, понятное пользователю сообщение (безопасное, вежливое, практическое) и внутренние детали (полная ошибка, стек и контекст) только в логах. Например: «Не удалось сохранить изменения. Пожалуйста, попробуйте ещё раз.» — безопасно. «pq: duplicate key value violates unique constraint users_email_key» — нельзя отдавать.

Когда все эндпоинты следуют одному контракту, клиенты могут написать один обработчик ошибок и переиспользовать его везде.

Определите схему ответа об ошибке, на которую можно опереться

Клиенты могут корректно обрабатывать ошибки только если каждый эндпоинт отвечает одинаковой формой. Выберите один JSON‑конверт и сохраняйте его стабильным.

Практический дефолт — объект error плюс топ‑уровневый request_id:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Some fields are invalid.",
    "details": {
      "fields": {
        "email": "must be a valid email address"
      }
    }
  },
  "request_id": "req_01HV..."
}

HTTP‑статус даёт широкую категорию (400, 401, 409, 500). Машиночитаемый error.code определяет конкретный случай, по которому клиент может ветвиться. Это важно, потому что многие разные проблемы делят один и тот же статус. Мобильное приложение может показать разный UI для EMAIL_TAKEN и WEAK_PASSWORD, хотя оба — 400.

Держите error.message безопасным и понятным человеку. Оно должно помогать пользователю исправить проблему, но никогда не раскрывать внутренности (SQL, трассы стека, имена провайдеров, пути файлов).

Опциональные поля полезны, если они остаются предсказуемыми:

• Ошибки валидации: details.fields как карта поле → сообщение.
• Ограничения по частоте или временные проблемы: details.retry_after_seconds.
• Дополнительные подсказки: details.docs_hint как простой текст (не URL).

Для обратной совместимости считайте значения error.code частью публичного контракта. Добавляйте новые коды, не меняя старые значения. Добавляйте только опциональные поля и предполагаете, что клиенты проигнорируют незнакомые поля.

Типизированные ошибки в Go: чистая модель для обработчиков

Обработка ошибок путается, когда каждый обработчик придумывает свой способ сигнализировать о сбое. Небольшой набор типизированных ошибок исправляет это: обработчики возвращают известные типы ошибок, а один слой перевода превращает их в согласованные ответы.

Практический стартовый набор покрывает большинство эндпоинтов:

• ValidationError (плохой ввод)
• NotFoundError (ресурс не найден)
• ConflictError (нарушение уникальности, несовпадение состояния)
• UnauthorizedError (не аутентифицировано или нет прав)
• InternalError (всё остальное)

Ключ — стабильность на верхнем уровне, даже если корневая причина меняется. Вы можете оборачивать низкоуровневые ошибки (SQL, сеть, парсинг JSON), при этом возвращая тот же публичный тип, который поймёт middleware.

type NotFoundError struct {
	Resource string
	ID       string
	Err      error // private cause
}

func (e NotFoundError) Error() string { return "not found" }
func (e NotFoundError) Unwrap() error { return e.Err }

В обработчике возвращайте NotFoundError{Resource: "user", ID: id, Err: err} вместо прямой утечки sql.ErrNoRows.

Для проверки ошибок предпочитайте errors.As для кастомных типов и errors.Is для sentinel‑ошибок. Сентинельные ошибки (например, var ErrUnauthorized = errors.New("unauthorized")) подходят для простых случаев, но пользовательские типы выигрывают, если нужно безопасно хранить контекст (например, какой ресурс отсутствует) без изменения публичного контракта ответа.

Будьте требовательны к тому, что вы добавляете:

• Публичное (безопасно для клиента): короткое сообщение, стабильный код и иногда имя поля при валидации.
• Приватное (только в логах): исходная Err, информация о стеке, сырые ошибки SQL, токены, данные пользователя.

Это разделение помогает помогать клиентам, не раскрывая внутренности.

Последовательное сопоставление типов ошибок с HTTP-статусами

Когда у вас есть типизированные ошибки, следующая задача — скучная, но необходимая: одному и тому же типу ошибки всегда соответствовать один и тот же HTTP-статус. Клиенты строят логику вокруг этого.

Практическое сопоставление, подходящее для большинства API:

Две важные грани, которые предотвращают путаницу:

• 400 vs 422: используйте 400, когда запрос нельзя надёжно интерпретировать (плохой JSON, неправильные типы). Используйте 422, когда вы можете распарсить запрос, но значения неприемлемы.
• 409 vs 422: используйте 422 для валидации на уровне поля (пароль слишком короткий). Используйте 409, когда данные валидны, но не применимы из‑за состояния (email уже занят, заказ уже отправлен, неудачная оптимистичная блокировка).

Рекомендации по повтору:

• Обычно безопасно повторять: 503, и иногда 429 (после ожидания).
• Обычно не безопасно повторять без изменений: 400, 401, 403, 404, 409, 422.
• Если операция идемпотентна (PUT с тем же телом или POST с idempotency key), повторы становятся безопаснее даже при временных ошибках.

Request ID: самый быстрый способ дебага клиентских проблем

Request ID — короткое уникальное значение, идентифицирующее один API‑вызов «сквозь» систему. Если клиенты видят его во всех ответах, поддержка упрощается: «Пришлите request ID» часто достаточно, чтобы найти точный лог и причину ошибки.

Эта практика полезна как для успешных, так и для ошибочных ответов.

Правила генерации и передачи

Используйте одно простое правило: если клиент прислал request ID — сохраните его. Если нет — создайте.

• Принимайте входной ID из одного заголовка (выберите один и документируйте, например X-Request-Id).
• Если заголовок отсутствует или пуст, генерируйте новый ID на краю (middleware) и кладите его в контекст запроса.
• Никогда не меняйте ID в ходе одного запроса. Передавайте его дальше в вызовы DB и в другие сервисы через context или заголовки.

Кладите request ID в три места:

• Заголовок ответа (тот же заголовок, который вы принимаете)
• Тело ответа (как request_id в стандартной схеме)
• Логи (как структурное поле в каждой строке лога)

Пакетная и асинхронная работа

Для batch‑эндпоинтов или фоновых задач держите родительский request ID. Пример: клиент загружает 200 строк, 12 валидируются с ошибкой, вы ставите задачи в очередь. Верните один request_id для всего вызова и укажите parent_request_id в каждой задаче и в ошибках по элементам. Так вы сможете трассировать «одну загрузку», даже если она разойдётся на множество задач.

Логирование и метрики без утечки внутренних данных

Клиенты нуждаются в понятном, стабильном ответе об ошибке. Ваши логи нуждаются в грязной правде. Разделяйте эти два мира: отдавайте клиенту безопасное сообщение и публичный код ошибки, а в логах храните внутреннюю причину, стек и контекст.

Логируйте одно структурированное событие для каждого ответного сообщения об ошибке, доступное для поиска по request_id.

Поля, которые стоит держать консистентными:

• request_id
• user_id или account_id (при аутентификации)
• публичный код ошибки и HTTP‑статус
• имя обработчика/маршрута и метод
• внутренняя деталь ошибки (wrapped cause, ошибки валидации полей, таймауты upstream)

Храните внутренние детали только в серверных логах (или в внутреннем хранилище ошибок). Клиент никогда не должен видеть сырые ошибки БД, текст запросов, трассировки стека или сообщения провайдеров. В распределённой системе поле вроде source (api, db, auth, upstream) ускорит триаж.

Следите за «шумными» эндпоинтами и ошибками по ограничению частоты. Если эндпоинт генерирует 429 или 400 тысячи раз в минуту, избегайте спама в логах: семплируйте повторяющиеся события или снижайте уровень важности, при этом считая их в метриках.

Метрики ловят проблемы раньше, чем логи. Считайте количества по HTTP‑статусам и кодам ошибок и ставьте алерты на резкие всплески. Если RATE_LIMITED вырос в 10 раз после деплоя, вы увидите это быстро даже при семплинге логов.

Шаг за шагом: реализуйте согласованный pipeline ошибок в Go

Проще всего сделать ошибки согласованными, перестав обрабатывать их «везде», и пустив их через один небольшой pipeline. Этот pipeline решает, что видит клиент, а что остаётся в логах.

Pipeline в 5 практических шагов

Начните с небольшого набора кодов ошибок, на который клиенты смогут опереться (например: INVALID_ARGUMENT, NOT_FOUND, UNAUTHORIZED, CONFLICT, INTERNAL). Оборачивайте их в типизированную ошибку, которая экспортирует только безопасные публичные поля (code, безопасное сообщение, опциональные details, например какое поле неверно). Внутренние причины держите приватными.

Затем реализуйте одну функцию‑транслятор, которая превращает любую ошибку в (statusCode, responseBody). Именно здесь типы ошибок мапятся на HTTP‑статусы, а неизвестные ошибки становятся безопасным 500.

Далее добавьте middleware, которое:

• обеспечивает наличие request_id у каждого запроса
• восстанавливает выполнение после паники

Паника никогда не должна сливать трассировки стека клиенту. Возвращайте обычный 500 с общим сообщением и логируйте полную панику с тем же request_id.

Наконец, поменяйте обработчики так, чтобы они возвращали error вместо непосредственной записи ответа. Один обёрточный слой вызовет обработчик, прогонит транслятор и запишет JSON в стандартном формате.

Короткий чеклист:

• Определите типизированные ошибки с безопасными полями и стабильными кодами.
• Переводите ошибки в статус и JSON в одном месте.
• Добавьте middleware для request ID и для recovery от паник.
• Сделайте обработчики возвращающими ошибки, а не пишущими ответы.
• Напишите "golden"‑тесты для транслятора и обёртки.

Golden‑тесты важны, потому что они фиксируют контракт. Если кто‑то позже поменяет сообщение или статус, тесты упадут до того, как клиенты получат неожиданные изменения.

Пример: один эндпоинт, три отказа, предсказуемые ответы

Представьте эндпоинт: клиент создаёт запись customer.

POST /v1/customers с JSON { \"email\": \"[email protected]\", \"name\": \"Pat\" }. Сервер всегда возвращает одну и ту же форму ошибки и всегда включает request_id.

1) Ошибка валидации (400)

Email отсутствует или имеет некорректный формат. Клиент может подсветить поле.

{
  "request_id": "req_01HV9N2K6Q7A3W1J9K8B",
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Some fields need attention.",
    "details": {
      "fields": {
        "email": "must be a valid email address"
      }
    }
  }
}

2) Конфликт (409)

Email уже существует. Клиент может предложить войти или выбрать другой email.

{
  "request_id": "req_01HV9N3C2D0F0M3Q7Z9R",
  "error": {
    "code": "ALREADY_EXISTS",
    "message": "A customer with this email already exists."
  }
}

3) Временный сбой (503)

Зависимость недоступна. Клиент может повторить с экспоненциальным бэкоффом и показать спокойное сообщение.

{
  "request_id": "req_01HV9N3X8P2J7T4N6C1D",
  "error": {
    "code": "TEMPORARILY_UNAVAILABLE",
    "message": "We could not save your request right now. Please try again."
  }
}

С одним контрактом клиент реагирует последовательно:

• 400: подсветить поля, используя details.fields
• 409: предложить безопасный следующий шаг пользователю
• 503: предложить повтор и показать request_id как идентификатор для поддержки

Для поддержки этот же request_id — самый быстрый путь к реальной причине в внутренних логах, без раскрытия стек‑трейсов или ошибок базы данных.

Распространённые ловушки, которые ухудшают обработку ошибок

Самый быстрый способ раздражать клиентов — заставить их угадывать. Если один эндпоинт возвращает { \"error\": \"...\" }, а другой — { \"message\": \"...\" }, каждый клиент превращается в груду специальных случаев, и баги скрываются неделями.

Типичные ошибки:

• Возвращать HTTP 200 с ошибкой в теле или переключаться между несколькими схемами ошибок на разных эндпоинтах.
• Открывать внутренности в пользовательском сообщении: SQL‑ошибки, трассировки стека, IP, имена хостов зависимостей, пути файлов.
• Использовать только человекочитаемый текст как идентификатор вместо стабильного code, по которому клиенты могут ориентироваться.
• Сменять коды ошибок легкомысленно (или использовать один код для разных проблем) и ломать клиентов, написанных под старое поведение.
• Добавлять request_id только при ошибках, тогда нельзя сопоставить пользовательский отчёт с успешным вызовом, повлёкшим потом ошибку.

Утечка внутренних данных — самая лёгкая ловушка. Обработчик возвращает err.Error() из удобства, и в продакшн попадает имя ограничения или сообщение третьей стороны. Держите сообщение для клиента безопасным и коротким, а подробную причину — в логах.

Ориентация только на текст — долгий пожар. Если клиент парсит английские предложения вроде «email already exists», вы не сможете менять формулировки без риска поломать логику. Стабильные коды ошибок позволяют менять сообщения, переводить их и сохранять поведение.

Относитесь к кодам ошибок как к части публичного контракта. Если нужно изменить код, добавьте новый и держите старый работающим некоторое время, даже если оба мапятся на один статус.

Наконец, включайте одно и то же поле request_id в каждый ответ, успешный или нет. Когда пользователь говорит «сначала работало, потом сломалось», этот один ID часто экономит час разбирательств.

Быстрый чеклист перед релизом

Перед выпуском пройдитесь по простому чек‑листу на согласованность:

• Одна форма ошибки везде. Каждый эндпоинт возвращает одинаковые поля JSON (например: error.code, error.message, request_id).
• Стабильные коды ошибок и покрытие. Держите коды короткими и понятными (VALIDATION_FAILED, NOT_FOUND, CONFLICT, UNAUTHORIZED). Напишите тесты, чтобы обработчики не возвращали незнакомые коды по ошибке.
• Одно правило маппинга на статусы. Решите, как каждый тип ошибки мапится на HTTP‑статус, и применяйте это в одном общем месте.
• Request ID в обе стороны. Всегда возвращайте request_id и логируйте его для каждого запроса, включая паники и таймауты.
• Безопасные сообщения по умолчанию. Пользовательские сообщения должны быть короткими, ясными и практичными; никогда не содержать трассировок стека, SQL‑ошибок или имён вендоров.

После этого прогоните пару ручных проверок. Вызовите ошибку валидации, обращение к несуществующей записи и неожиданную ошибку. Если ответы выглядят по‑разному на разных эндпоинтах (поля меняются, статус дрейфует, сообщения раскрывают лишнее) — исправьте общий pipeline прежде, чем добавлять новые фичи.

Правило: если сообщение поможет злоумышленнику или запутает обычного пользователя, оно должно оставаться в логах, а не в ответе.

Следующие шаги: стандартизируйте сейчас и поддерживайте позже

Опишите контракт ошибок, которому должны следовать все эндпоинты, даже если API уже в продакшне. Общий контракт (статус, стабильный код ошибки, безопасное сообщение и request_id) — самый быстрый путь сделать ошибки предсказуемыми для клиентов.

Мигрируйте постепенно. Сохраните существующие обработчики, но пропустите их ошибки через один маппер, который превращает внутренние ошибки в публичную форму. Это повышает согласованность без рискованного большого рефактора и не позволит новым эндпоинтам придумывать формат.

Ведите небольшой каталог кодов ошибок и относитесь к нему как к части API. Если кто‑то хочет добавить новый код, быстро проверяйте: действительно ли он новый, понятное ли у него имя и соответствует ли он правильному HTTP‑статусу.

Добавьте несколько тестов, которые ловят дрейф:

• Каждый ответ с ошибкой содержит request_id.
• Статус кода соответствует типу ошибки (а не тексту ошибки).
• error.code присутствует и берётся из каталога.
• error.message безопасно и не содержит внутренних деталей.
• Неизвестные ошибки откатываются к 500 с общим сообщением.

Если вы строите backend на Go с нуля, полезно закрепить контракт на раннем этапе. Например, Koder.ai (koder.ai) включает режим планирования, где можно заранее прописать соглашения, такие как схема ошибок и каталог кодов, а затем держать обработчики в соответствии с ними по мере роста API.