Определите проблему
Описывайте условие возникновения ошибки, а не только код и сообщение. Справочник ошибок полезен, если помогает распознать сбой, понять причину и безопасно восстановиться, а не просто повторяет код ошибки.
Выберите рабочую модель
Показывайте стабильные поля ответа, типы и назначение request или trace identifier. На уровне реальных гарантий API описывайте статус, машинный код, сообщение, вероятную причину, возможность повтора и действие для исправления.
Встройте в процесс
Давайте стратегию восстановления: повторить, изменить ввод, обновить учётные данные, подождать, обратиться к администратору или остановиться. Разделяйте ошибки аутентификации, валидации, rate limit и сервера: безопасные стратегии восстановления у них разные.
Проверьте результат
Разделяйте валидацию, права, конфликты, rate limit и серверные ошибки, потому что действия после них разные. Примеры должны показывать форму ответа и реалистичный путь исправления, чтобы клиентское приложение можно было проверить до production.
Сохраните сопровождаемость
Примеры должны совпадать с реальными полями и регистром ответа: обработку ошибок часто копируют прямо из документации. По возможности связывайте перечень ошибок с тестами или схемами реализации: новый недокументированный код фактически меняет контракт для клиентов.
Практический разбор
Превратите «Как документировать ошибки API, чтобы разработчик мог восстановиться» в одну законченную задачу разработчика. Возьмите вымышленный, но реалистичный ресурс — например отчёт, устройство или заказ — и опишите кратчайший путь от аутентификации до успешного результата. Включите запрос, важные поля ответа, одну вероятную ошибку и следующее действие после неё. Пример должен быть принципиально выполнимым даже без живого сервиса.
Проверьте его так, будто по нему действительно пишут клиент:
- какие значения разработчик обязан заменить;
- какие идентификаторы возвращает сервер и где они используются дальше;
- какой статус или поле подтверждает успех;
- что делать при ошибке credentials, входных данных или rate limit.
Если ответы разбросаны по несвязанным страницам, документация может быть формально полной, но практически слабой. Хорошая API-документация позволяет предсказать взаимодействие с системой, а не только узнать названия endpoint-ов.
Короткий редакционный чек-лист
- Определите проблему. Описывайте условие возникновения ошибки, а не только код и сообщение.
- Выберите рабочую модель. Показывайте стабильные поля ответа, типы и назначение request или trace identifier.
- Встройте в процесс. Давайте стратегию восстановления: повторить, изменить ввод, обновить учётные данные, подождать, обратиться к администратору или остановиться.
- Проверьте результат. Разделяйте валидацию, права, конфликты, rate limit и серверные ошибки, потому что действия после них разные.
