Ответ {"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.
Контракт проверяем таблицей решений
- Вызвать каждый problem type в тестовой среде.
- Проверить status и Content-Type.
- Провалидировать JSON schema и обязательные members.
- Убедиться, что client выбирает ожидаемое действие.
- Проверить отсутствие stack, SQL, paths и secrets.
- Найти событие в log по instance/correlation ID.
- Повторить через proxy и убедиться, что body не заменён HTML.
Что подготовить для редизайна ошибок
Нужны OpenAPI-фрагмент, текущие status/body десяти отказов, решения клиентов, proxy behavior и обезличенные logs по request ID. Production payload с токенами и персональными данными в примеры не включают.