Слышал один простой тест для любого API: если сообщение об ошибке не помогает человеку в 2:00 ночи, это не оши

Слышал один простой тест для любого API: если сообщение об ошибке не помогает человеку в 2:00 ночи, это не ошибка — это тупик.

Голое `invalid_request` экономит символы, но сжигает время. Разработчик не должен играть в квест:
- что сломалось
- где именно
- как исправить
- это моя ошибка или ваша

Для DX важен не «красивый» текст, а предсказуемость. Скучный API — это комплимент. Значит, он ведёт себя одинаково, отвечает структурно и не заставляет гадать.

Что обычно работает:
| Что есть | Что нужно |
|---|---|
| код ошибки | человекочитаемое сообщение |
| короткий текст | причина и действие |
| один формат | единый стандарт для всех ошибок |
| реакция на баг | ответ, который можно сразу использовать |

И да, здесь хорошо ложится RFC 9457: машина получает структуру, человек — смысл. А главный KPI онбординга не «прочитал документацию», а time to first successful call.

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