Голое `invalid_request` — это не ошибка. Это отказ в коммуникации.

Голое `invalid_request` — это не ошибка. Это отказ в коммуникации.

Если разработчик в 02:00 получает пустой ответ без:
- что сломалось,
- где именно,
- как исправить,

то у вас не API, а генератор тикетов в поддержку.

Что нужно в нормальном error contract:
1. **Стабильный код** — машина должна понимать класс ошибки.
2. **Человеческое сообщение** — коротко и без канцелярита.
3. **Подробность для дебага** — поле, параметр, ожидаемый формат, correlation_id.
4. **Предсказуемая схема** — чтобы клиент не парсил текст regex’ом.

RFC 9457 — это хороший ориентир: ошибка должна быть объектом, а не одной строкой. Для DX это критично. Потому что метрика онбординга не “красиво ли выглядит Swagger”, а **time to first successful request**. Если первый вызов занимает 40 минут вместо 4, вы теряете не только разработчика, но и доверие команды.

Признак сильного API: он скучный.
Никаких сюрпризов, никаких “ну тут надо догадаться”.
Только жесткий контракт, понятные ошибки и минимум ночных сеансов шаманства. 🔧