Коды ошибок и статусы

Узнать ошибку по коду

Коды статусов не отображаются в тебе ответа. Они содержатся в хэдере, который может быть не видим по умолчанию.

Заголовок ответа выглядит следующим образом:

Коды состояния довольно тонкие, но когда разработчик работает с API, коды могут быть единственным «интерфейсом», который имеет разработчик. Если получится контролировать сообщения, которые видит разработчик, это будет большой победой юзабилити

Слишком часто коды состояния неинформативны, плохо написаны и сообщают мало или вообще никакой полезной информации пользователю для преодоления ошибки. По большому счету, коды состояния должны помогать пользователям в восстановлении после ошибок.

Можно посмотреть список общих кодов состояния REST API здесь и общий список кодов HTTP статусов здесь. Хотя, возможно, было бы полезно включить несколько стандартных кодов состояния, нет необходимости в полном документировании всех стандартных кодов состояния, особенно если они редко запускаются в API.

Где перечислять HTTP-ответ и коды ошибок

Практичнее, если API будут иметь одну страницу с ответами и кодами ошибок ко всему API. Отдельная страница с перечнем кодов состояния (вместо добавления кода состояния в каждую конечную точку) позволяет более детально описать каждый код без переполнения других частей документации. Такой подход уменьшает избыточность и ощущение информационной перегрузки.

С другой стороны, если какие-то коды состояния и ошибок больше подходят к определенным конечным точкам, чем другие, имеет смысл вывести такие коды состояния и ошибок на страницы с описаниями конечных точек.

Такая стратегия может заключаться в том, чтобы привлечь внимание к каким-либо особенно важным кодам состояния или ошибок для конкретной конечной точки, а затем перейти к централизованной странице «Коды ответов и состояний» для получения полной информации.

Где взять коды ошибок и статусы

Коды состояния и ошибок могут быть неочевидны в документации API. Вероятно, придется попросить разработчиков предоставить список всех кодов состояния и ошибок, которые уникальны для API. Иногда разработчики хардкодят коды состояния и ошибок непосредственно в программном коде, и у них нет простых способов передать полный список (что также затрудняет локализацию).

В результате может потребоваться танцы с бубнами, чтобы найти все коды. В частности, возможно придется сломать API, чтобы увидеть все возможные коды ошибок. Например, если превысить ограничение скорости для определенного запроса, API может вернуть специальную ошибку или код состояния. Такой пользовательский код обязательно нужно задокументировать. В разделе устранения неполадок в API можно специально разместить примеры получения кодов ошибок.

Как перечислять коды ошибок

Коды статусов и ошибок можно привести в виде списка определений или таблицы, например так:

Коды состояния и ошибок помогают в устранении неполадок

Коды состояния и ошибок особенно полезны при устранения неполадок. Таким образом, можно рассматривать коды ошибок как дополнение к разделу по устранению неполадок.

Каждая часть документации может быть полезна в разделе, посвященном устранению неполадок. В разделе, посвященном устранению неполадок, можно описать, что происходит, когда пользователи уходят с проторенной дорожки и спотыкаются в темном лесу. Коды состояния похожи на подсказки, которые помогут пользователям вернуться на правильный путь.

В разделе по устранению неполадок можно перечислить сообщения об ошибках, связанных со следующими ситуациями:

текст ошибки должен точно документироваться, чтобы она легко появлялась при поиске.

Примеры кодов статусов и ошибок

Ниже приведены несколько вариантов разделов с кодами статусов и ошибок.

Context. io

В своем найденном опен-сорс проекте найдем информацию о кодах статусов и ошибок. Ответим на следующие вопросы:

Как узнать причину синего экрана смерти Windows (BSoD)

Чтобы не теряться, когда на экране внезапно засветился синий «фонарь», нужно уметь смотреть неприятелю «в лицо». То есть научиться выяснять, что привело к появлению BSoD’a, оценивать, насколько ситуация критична и знать, что делать, чтобы она больше не повторялась.

«Синий фонарь» включается неожиданно

Синие экраны смерти возникают на любой стадии загрузки и работы компьютера. А приводит к ним следующее:

Кстати, однократный BSoD после подключения к компьютеру нового девайса, если в дальнейшем всё работает без нареканий, можно считать нормой.

Что можно узнать из информации на синем экране

Аппаратные «синяки» чаще возникают в одних и тех же условиях (например, при увеличении нагрузки на видеокарту, попытке открыть объемный файл) и имеют разные коды. Либо эти коды указывают на проблемы конкретного оборудования, как то: ошибки доступа к устройству, невозможность считывания, распознавания.

Однако эти признаки позволяют сделать лишь предположение о причине проблемы. Для ее уточнения необходимы более детальные сведения.

Синий экран смерти Windows 10 выглядит так:

Информацию об ошибке в нем несет строка «Stop code». В моем примере это CRITICAL PROCESS DIED.

Отсканировав телефоном QR-код, который находится здесь же, вы можете перейти на сайт windows com/ stopcode, где содержатся общие советы по устранению сбоя. Подсказки от Microsoft иногда полезны, но о причине конкретно вашего случая там ничего нет, а значит, придется искать эти данные в другом источнике, например:

Но и это не совсем полные сведения. Каждая ошибка уникальна, и самая точная информация о ней содержится в файле, который система сохраняет на диск в момент сбоя. А именно – в малом дампе памяти, которые мы и будет учиться анализировать. А чтобы такие файлы создавались, необходимо сделать несколько маленьких настроек.

Как включить функцию создания и сохранения малых дампов памяти

Для сохранения дампов памяти на жестком диске системе обязательно нужен файл подкачки, который должен находиться в том же разделе, где папка Виндовс. Его размер может быть от 2 Mb и больше.

На этом настройка закончена. Теперь информация о BSoD’ах будет сохраняться в вышеуказанном каталоге.

Как анализировать содержимое минидампов

BlueScreenView особенно удобна тем, что не требует установки на компьютер громоздких пакетов Debugging Tools for Windows и может запускаться с любого носителя, достаточно кликнуть по одноименному файлу.

Интерфейс утилиты, несмотря на отсутствие русского языка, весьма дружелюбен. Главное окно разделено на 2 половины. Вверху – таблица минидампов – файлов из папки Windows\Minidump с датой и временем создания (колонка Crash Time), кодом ошибки в шестнадцатеричном формате (колонка Bug Check Code), четырьмя ее параметрами и другими сведениями. Впрочем, данные о конкретном сбое удобнее просматривать в отдельном окне, которое открывается двойным щелчком по интересующей строке (показано ниже). Главное окно дает больше информации о проблеме в целом, если BSoD’ы случались неоднократно. В нем легко отслеживать даты происшествий и коды ошибок, по повторяемости которых можно судить о характере неполадки.

Нижняя половина основного окна отображает драйвера, загруженные в память в момент аварийной ситуации по конкретному дампу, выделенному в списке. Строки, подсвеченные розовым, показывают содержимое стека потока событий, а упомянутые в них драйвера имеют самое прямое отношение к причине сбоя.

Разберем для примера один из малых дампов памяти с кодом ошибки 0x00000154. Скажу наперед, что он был вызван заломом шлейфа жесткого диска. Начиная анализ, посмотрим на список драйверов в стеке событий. Здесь нет ничего, кроме ntoskrnl. exe – ядра ОС Windows, которое, конечно, в проблеме не виновато – просто во время сбоя ни одного драйвера в стеке не было, а оно присутствует там всегда.

Далее заглянем в окошко параметров дампа. Здесь тоже не упомянуто ничего, кроме ntoskrnl. exe, значит, проблема вызвана не драйвером.

Для проверки этой версии оценим показатели S. M.A. R.T жесткого диска компьютера, которые отслеживает программа Hard Disk Sentinel. В день аварии здесь появились изменения следующих атрибутов:

Оба указывают на ошибки передачи данных по интерфейсному кабелю. Тест поверхности харда и проверка файловой структуры отклонений не выявили, поэтому проблема была решена заменой шлейфа.

Рассмотрим еще один случай синего экрана смерти, причиной которого стал антивирус Касперского. BSoD периодически возникал во время запуска Windows 10 и при выходе компьютера из спящего режима.

Ошибка зафиксировалась несколько раз под одним и тем же кодом – 0x000000d1, который означает следующее: «драйвер режима ядра попытался получить доступ к странице памяти в процессе IRQL, который имел слишком высокий приоритет». На этот раз BlueScreenView указал на проблему в драйвере NDIS. sys, отвечающем за сетевые подключения. Значит, высока вероятность, что сбой имеет программное происхождение и связан с чем-то, что использует сеть.

Для выявления виновника потребовалось провести анализ автозагрузки приложений. На раннем этапе запуска операционной системы этого ПК стартовало не слишком много программ, которым разрешен доступ в Интернет, точнее, один Касперский. В подтверждение его причастности я снова обратилась к списку загруженных в память драйверов в BlueScreenView и среди того, что присутствует здесь обычно, обнаружила kl1.sys, принадлежащий антивирусу.

После удаления Касперского синие экраны больше не выскакивали.

Утилита BlueScreenView позволяет анализировать аварийные дампы памяти, полученные не только там, где она запущена, но и на другом компьютере. Для этого не нужно копировать их в папку Windows\ Minidump своего ПК, которая загружается в программу по умолчанию. Скопируйте их в любое удобное место, например, на рабочий стол, и укажите программе новое расположение каталога, который следует загружать.

Функция выбора папки с файлами дампов находится в меню «Options» – «Advanced Options» (открывается сочетанием клавиш Ctrl + O) и называется «Load from the following minidump folder».

Установив здесь отметку, кликните кнопку «Browse» и найдите нужный каталог в проводнике. Когда захотите вернуть настройки по умолчанию, нажмите «Default».