«invalid_request» — это не ошибка. Это издевательство.

«invalid_request» — это не ошибка. Это издевательство.

Два часа ночи, у разработчика горит релиз, он впервые подключает ваш API, получает сухое сообщение и… дальше сорок минут на угадайку. Что сломалось? Где смотреть? Это поле? Это формат? Это версия? Ноль ответов. Только усталость, раздражение и письмо в поддержку.

Вот чёрный кейс, который до сих пор встречается слишком часто: команды вкладываются в фичи, документацию, дизайн, а на самом базовом месте — в сообщениях об ошибках — оставляют пустоту.

Если ваш API не умеет объяснять проблему, он ломает онбординг.
Если человек не может быстро понять, что делать дальше, ваш «удобный продукт» превращается в квест.

Хорошая ошибка отвечает на три вопроса:
— что случилось
— почему это произошло
— как исправить

Это и есть человеческий DX. Не «умные» формулировки, а предсказуемость. Не драматичный интерфейс, а скучная ясность. И да, «скучный» API — это комплимент. Потому что с ним можно работать без шаманства.

Минимальный стандарт для ошибки:
- код
- короткое объяснение
- причина
- шаг для исправления
- ссылка на документацию или пример

Первый успешный вызов — это не мелочь. Это главная метрика онбординга. Всё, что до него, должно сокращать путь, а не удлинять его. ✦