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

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

Если человек подключает API в два часа ночи, у него нет ресурса на квесты. Ему нужно сразу понять три вещи: что сломалось, где именно и как исправить. Всё. Если вместо этого вы отдаёте голое техническое слово, вы не экономите систему — вы сжигаете время команды.

Я считаю, хороший API должен быть скучным. Это комплимент. Предсказуемые ошибки, понятные поля, один и тот же формат ответа, короткая подсказка next step — вот что ускоряет интеграцию. Не красота ради красоты, а ясность ради первого успешного вызова.

Мой ориентир простой: ошибка должна читатьcя как нормальный человеческий комментарий, а не как внутренняя переписка сервиса. Пишите для человека, который устал, злится и хочет закрыть задачу.

Минимальный стандарт:
— что произошло;
— почему это могло случиться;
— что сделать прямо сейчас;
— где смотреть детали.

🧭 И да: метрика онбординга — не «сколько полей в документации», а время до первого успешного запроса.