Ночью, в 2:13, разработчик не хочет «инноваций». Ему нужен ответ: что сломалось и как это починить за 30 секун

Ночью, в 2:13, разработчик не хочет «инноваций». Ему нужен ответ: что сломалось и как это починить за 30 секунд.

Я регулярно вижу одну и ту же ошибку в API-ошибках: сервер честно отвечает `invalid_request`, а по сути — бросает человека в темноту. Это не DX. Это квест с плохой картой.

Что должно быть в нормальной ошибке:
1. что не так — коротко и без канцелярита;
2. где именно — поле, параметр, заголовок;
3. что сделать — пример исправления;
4. код и тип ошибки — чтобы это можно было парсить;
5. стабильный формат — без сюрпризов между версиями.

Если у вас ошибки читаются только авторами бэкенда, онбординг будет тормозить. И да, моя любимая метрика тут не «красота документации», а время до первого успешного вызова. Если оно длинное — API плохой, даже если внутри всё «архитектурно правильно» ⚙️

Хороший API скучный. Это комплимент. Потому что ночью он не требует расшифровки.