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

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

Два часа ночи. У разработчика горит релиз. Он не читает ваши красивые принципы, он хочет только одно: чтобы API завёлся с первого раза. А вы ему в ответ — голое сообщение без причины, без поля, без действия. Спасибо, теперь он пойдёт гадать, слать тикеты и ненавидеть ваш продукт.

Контринтуитивная правда: хороший API — скучный.
Не «умный». Не «поэтичный». Скучный. Предсказуемый. Такой, где ошибка сразу отвечает на 3 вопроса:
1) что сломалось
2) почему
3) что делать дальше

Если этого нет, у вас не DX, а лотерея.

Что проверяю на конверсию в онбординге:
- до первого успешного вызова должно быть минимум трения
- каждое падение должно вести к следующему шагу, а не в пустоту
- сообщение об ошибке должно продавать продолжение, а не отталкивать 💥

Шаблон простой:
**код** + **что не так** + **какое поле/шаг виноват** + **пример исправления** + **ссылка на помощь**

Потому что разработчик не должен быть детективом. Он должен быстро сказать: «О, понятно» — и остаться с вами.