Все думают, что API-ошибка должна быть «краткой и чистой». На практике это часто просто `invalid_request` — и

Все думают, что API-ошибка должна быть «краткой и чистой». На практике это часто просто `invalid_request` — и минус 40 минут жизни у разработчика в 2:00 ночи.

Для DX это плохой паттерн. Ошибка должна отвечать на 3 вопроса сразу: **что сломалось**, **почему**, **что делать дальше**. Иначе вы продаёте не продукт, а квест на выживание.

Что работает лучше:
- структурированный формат ошибок, близкий к RFC 9457
- стабильные коды, без сюрпризов между версиями
- человекочитаемое `message` + `details` + `next_step`
- пример исправления прямо в ответе

Главная метрика онбординга — не «сколько документации прочитали», а **time to first successful call**. Если она длинная, ваш API дорогой в поддержке, даже если формально «полностью documented».

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