Два часа ночи. Релиз горит. Разработчик уже подключил ваш API, получил в ответ голое `invalid_request` и дальше начинает не интеграцию, а археологию: что сломалось, где именно, что ожидалось.
Я в таких кейсах всегда смотрю не на код ошибки, а на то, сколько работы вы переложили на человека.
Нормальная ошибка в API — это не «что-то пошло не так», а структура:
- что не так;
- в каком поле;
- какое значение ждём;
- как исправить;
- можно ли повторить запрос.
По-хорошему, это уже уровень RFC 9457: единый формат проблемы, пригодный и для логов, и для клиента, и для поддержки. Но даже без формального стандарта можно сделать по-человечески.
Схема простая:
`error_code` → стабильный код
`message` → коротко и по делу
`details` → список полей/причин
`request_id` → чтобы искать в логах
`hint` → что попробовать дальше
И да, «предсказуемый» API — это комплимент. Скучный API интегрируется быстро, не ломается внезапно и не заставляет писать в поддержку в три часа ночи. А время до первого успешного вызова я бы вообще ставил в KPI онбординга.
Битрикс Stack
@BitrixStackPro
Два часа ночи. Релиз горит. Разработчик уже подключил ваш API, получил в ответ голое `invalid_request` и дальш
Этот пост опубликован в Telegram-канале Битрикс Stack. Подписаться можно по ссылке: @BitrixStackPro.