Голое `invalid_request` в ответе на ошибку — это не “строгость API”, а лишние 40 минут у разработчика и минус

Голое `invalid_request` в ответе на ошибку — это не “строгость API”, а лишние 40 минут у разработчика и минус доверие к продукту.

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

Что это значит для бизнеса:
- растёт время до первого успешного вызова;
- падает скорость онбординга;
- увеличивается нагрузка на саппорт;
- API воспринимается как “сложный”, даже если он технически нормальный.

Что делать:
1. Писать ошибку так, чтобы по ней можно было действовать.
2. Добавлять код, краткое объяснение, что пошло не так, и пример исправления.
3. Если возможно — указывать поле, значение и ожидаемый формат.
4. Держать формат ответов предсказуемым, чтобы человек не гадал после каждого запроса.

Хороший API — не тот, который выглядит умным. Хороший API — тот, который помогает дойти до первого успеха без лишних кругов 🛠️

Если хотите проверить себя, смотрите на одну метрику: сколько времени проходит от первого запроса до первого успешного ответа. Это честнее любого “у нас всё интуитивно”.