Ответ {"error":"bad request"} сообщает только факт отказа. Клиенту нужно понять действие: исправить поле, войти заново, не повторять запрещённую операцию, обновить версию ресурса, подождать или показать reference службе поддержки. Начните с корректного HTTP status и стабильного типа проблемы.

Не подменяйте полезность stack trace, SQL-текстом или именем внутреннего сервиса. Такие детали уходят в закрытый log по correlation ID, а публичный ответ описывает нарушение контракта API.

Статус задаёт общий класс решения

StatusСмысл для клиентаТипичное действие
400Запрос синтаксически некорректенИсправить JSON/header
401Нет действующей аутентификацииПолучить/обновить credentials
403Личность известна, действие запрещеноНе повторять без новых прав
404Ресурс не найден или скрыт политикойПроверить ID без перебора
409Конфликт с текущим состояниемПеречитать resource и решить конфликт
422Формат понятен, данные не проходят правилаПоказать ошибки полей
429Лимит запросовУчесть Retry-After и backoff

Problem Details создаёт общий конверт

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

{
  "type": "https://api.example.test/problems/version-conflict",
  "title": "Resource version conflict",
  "status": 409,
  "detail": "Reload the resource and retry with its current version.",
  "instance": "/problems/req-7f31",
  "current_version": 18
}

RFC 9457 определяет application/problem+json и базовые members type, title, status, detail и instance; domain fields можно добавлять как extensions. Адреса условные. instance идентифицирует конкретный случай и не должен раскрывать database key, hostname или персональные данные.

type стабилен, detail меняется по случаю

Клиент ветвится по status и problem type, а не сравнивает локализованный detail. Type URI находится под контролем API и документирует способ исправления. Title коротко называет класс проблемы; detail объясняет этот occurrence безопасным человеческим языком.

Версию problem contract меняют так же аккуратно, как обычный response schema. Добавление optional extension обычно совместимо, а переименование type ломает retry и UI-логику клиентов.

Validation errors указывают точное место

  • Использовать JSON Pointer или документированный field path.
  • Возвращать стабильный code правила, а не только текст.
  • Не эхоить secret, password и полный исходный payload.
  • Сохранять порядок ошибок только если он является контрактом.
  • Ограничивать число и размер ошибок в одном ответе.

Для массива ошибок одного типа RFC 9457 показывает extension errors с detail и pointer. Если проблемы разных типов, спецификация рекомендует представить наиболее важную; batch API может определить собственную модель результатов по элементам.

Correlation ID связывает ответ и закрытый log

Сгенерируйте request ID на доверенном edge либо проверьте формат входного ID, передайте его по сервисам и верните безопасную ссылку instance или отдельный header. В log добавьте exception class, stack, service, trace и actor ID по политике доступа. Пользователю достаточно reference и понятного следующего шага.

Ошибки не должны менять политику доступа

OWASP рекомендует использовать общие сообщения и не раскрывать stack traces. Разница между 403 и 404 для закрытого объекта выбирается сознательно: подробный ответ не должен превращаться в oracle существования чужих IDs. Одинаковая политика применяется к body, времени ответа и audit.

Контракт проверяем таблицей решений

  1. Вызвать каждый problem type в тестовой среде.
  2. Проверить status и Content-Type.
  3. Провалидировать JSON schema и обязательные members.
  4. Убедиться, что client выбирает ожидаемое действие.
  5. Проверить отсутствие stack, SQL, paths и secrets.
  6. Найти событие в log по instance/correlation ID.
  7. Повторить через proxy и убедиться, что body не заменён HTML.

Что подготовить для редизайна ошибок

Нужны OpenAPI-фрагмент, текущие status/body десяти отказов, решения клиентов, proxy behavior и обезличенные logs по request ID. Production payload с токенами и персональными данными в примеры не включают.

Проверенные источники