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

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

Ночной кейс: разработчик в 02:00 подключает API, ловит голый код без пояснений и тратит 40 минут на угадайку. Итог предсказуем: злой тикет в поддержку, потерянный темп релиза, лишняя нагрузка на CS.

Вот где ломается DX:
- error code есть, а действия нет;
- неясно, какой параметр сломан;
- нет примера исправления;
- нет статуса/контекста, можно ли ретраить.

Что делать:
1) Пишите ошибки по RFC 9457-логике, но человеческим языком: что сломалось, где, почему, как чинить.
2) Добавляйте метрику time to first successful call — это честнее, чем «сколько доки прочитали».
3) Делайте API «скучным»: предсказуемый формат ответа, одинаковая структура ошибок, стабильные коды. Это не скучно — это снижает churn на онбординге 📉

Шаблон ошибки:
- code
- message
- field
- expected
- example_fix
- retryable

Если ваш API заставляет людей гадать в 2 ночи — это не edge case. Это баг продукта.