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

Коды состояния и ошибок — это число в заголовке ответа, который указывает общую классификацию ответа — например, был ли запрос успешным (200), привел ли к ошибке сервера (500), были ли проблемы с авторизацией (403), и так далее. Стандартные коды состояния обычно не требуют большого количества документации, но пользовательские коды состояния и ошибки, специфичные для API, нужны. Коды ошибок, в частности, помогают в устранении неисправных запросов.

Пример кода статуса в заголовке curl

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

Помните, когда мы отправляли обратный вызов в разделе Создание curl запроса? Чтобы получить заголовок ответа, добавляем – include или — i к запросу curl. Если нужно, чтобы в ответе возвращался только заголовок ответа (и ничего больше), используем заглавную букву — I, например:

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

Первая строка, HTTP / 1.1 200 OK , сообщает нам статус запроса ( 200 ). Большинство API REST следуют стандартному протоколу для заголовков ответов. Например, 200 — это не просто произвольный код, выбранный разработчиками OpenWeatherMap API. 200 — это общепринятый код для успешного HTTP-запроса. (Если изменить метод, то получим другой код состояния.)

С помощью запроса GET довольно легко определить, успешен ли запрос, потому что получаем ожидаемый ответ. Но предположим, делаем запрос POST, PUT или DELETE, когда мы меняем данные, содержащиеся в ресурсе. Как узнать, был ли запрос успешно обработан и получен API? Коды ответа HTTP в заголовке ответа будут указывать, была ли операция успешной. Коды состояния HTTP — это просто сокращения длинных сообщений.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Context. io

Clearbit не только документирует стандартные коды состояния, но также описывает уникальные параметры, возвращаемые их API. Большинство разработчиков, вероятно, знакомы с кодами 200, 400 и 500, поэтому эти коды не требуют много пояснений. Но если API имеет уникальные коды, описывать их нужно адекватно и подробно.

Twitter

В Twitter не только описывается код и состояние, но также предоставляется полезная информация по устранению неполадок, потенциально помогая в устранении ошибок. Например, про ошибку 500 не просто сказано, что статус относится к неработающей службе, но и есть объяснение: «Обычно это временная ошибка, например, в ситуации высокой нагрузки или если у конечной точки временно возникают проблемы. Посетите форумы разработчиков на случай, если у других возникнут аналогичные проблемы, или повторите попытку позже».

Полезные сообщения такого рода — то, к чему должны стремиться технические писатели в разделе кодов состояния (по крайней мере, делать описания тех кодов, которые указывают на проблемы)

Mailchimp

Mailchimp предоставляет удобочитаемые и понятные описания сообщений об ошибке. Например, в ошибке 403 вместо того, чтобы просто написать «Запрещено», Mailchimp объясняет причины, по которым можно получить ошибку запрещенного кода. У Mailchimp существует несколько типов ошибок 403. Запрос может быть запрещен из-за отключенной учетной записи пользователя или запроса, направленного не в тот центр обработки данных. В случае ошибки «WrongDataCenter» Mailchimp отмечает, что «она часто связана с неправильно настроенными библиотеками» и ссылается на дополнительную информацию о центрах обработки данных. Такой тип документации кода ошибки очень полезен для пользователей.

Flickr

В Flickr раздел «Коды ответов» встроен в описание каждой адресной темы API. Описания ошибок выглядят короткими. Хотя встраивание кодов ответов в каждую тему делает коды ошибок более заметными, в некоторых случаях такой подход менее полезен. Поскольку он встроен в каждую тему API, описания кодов ошибок должны быть краткими, иначе их содержимое будет перегружено информацией о запросе конечной точки.

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

?‍? Практическое занятие: Коды статусов и ошибок

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

Что делать, если произошла ошибка Андроид: коды, расшифровка, как исправить

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

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

Решается ошибка 24 очисткой остаточных данных:

1. Скачиваем и устанавливаем понравившийся файловый менеджер (как пример, ES Проводник)
2. Переходим к директории «sdcard/Android/data/data», в которой по названиям папок находим нужное приложение
3. Удаляем папки с вложениями

После этого ошибка 24 должна исчезнуть, а приложения без запинок устанавливаться на ваше Android — устройство.

В некоторых случаях рекомендуется почистить кэш Google Play . Для этого достаточно перейти к списку установленных приложений в настройках, найти Google Play и нажать соответствующую кнопку.

Ошибка 403 на Android

Еще одна назойливая ошибка Андроид, которая возникает при попытке установить программу или игру из Google Play . Причин возникновения уйма: от сбоев при подключении к Интернету до ошибок синхронизации аккаунтов Google . Решений тоже немало:

1. Для начала просто попробуйте заново подключиться к сети Wi — Fi (или проверьте подключение к мобильному интернету)
2. Очистите память устройства (проверить, сколько места осталось, можно в: «Настройки» — «Память»)
3. Однако самым распространенным источником ошибки 403 на Андроид является аккаунт Google , а вернее разного рода сбои синхронизации. Решается проблема довольно просто:

1. Зайдите в «Настройки» — «Аккаунты и синхронизация», где выберите « Google »
2. Отключите автоматическую синхронизацию, деактивировав переключатель
3. Перезагрузите Android — устройство, включите синхронизацию

1. Не лишней будет очистка кэша приложения Google Play (как описано в предыдущем пункте)

С ошибкой 403 на Андроид приходится бороться и каждому жителю Крыма. Дело не в сбоях, а в санкциях, которые должна исполнять Google , находясь под юрисдикцией США. Однако проблема решается очень просто с помощью VPN . О VPN и обходах блокировки на Андроид мы подготовили отдельный материал.

Ошибка 506 на Android при установке программ

Причиной ошибки, как правило, становятся сбои в работе Google Play или же сбоями в аккаунте Google .

На Андроид есть куча ошибок при установке приложений, которые очень напоминают ошибку 506. Логично, что и решаются они похожим способом. К ним можно отнести: 491, 495, 413, 941, 921, 920, 481 и некоторые другие.

1. Проверяем правильность настройки времени
2. Убеждаемся, что у нас достаточно памяти для установки приложения
3. Перезагружаем смартфон – на всякий случай
4. Чистим кэш приложения Google Play , как мы уже описывали (находим в списке приложений нужное, жмем «Очистить кэш)
5. Также почистить кэш можно и в других программах, связанных с Google (Сервисы Google Play, Services Framework)
6. Выйти из аккаунта Google , перезагрузить смартфон или планшет, войти в аккаунт

Ошибка 963 на Андроид

Преимущественно она преследует владельцев некоторых моделей смартфонов HTC , которые устанавливают или обновляют приложения в Google Play . Решений проблемы несколько, все довольно простые:

1. Если обновляемое приложение на карте памяти, попробуйте вернуть его во внутреннюю память устройства.
2. Возможно, поможет решить проблему отключение карты памяти. Делается это в разделе «Память» в настройках устройства. После этого попробуйте устанавливать приложения. Если все скачивается, обратно включите microSD .
3. Опять же, проблема может крыться в кэше приложений от Google . Очищаем его. Также можно попробовать удалить обновления для Google Play . Производится это в настройках приложений. Не забудьте перезагрузить устройство.

Ошибка при синтаксическом анализе на Android

Очень старая проблема на ОС Андроид, с которой сталкивался если не каждый первый, то каждый второй пользователь. Возникает она непосредственно в процессе установки приложений расширения . apk (как правило, скаченных не из Google Play ). Причин возникновения ошибки при синтаксическом анализе огромное множество, начиная с банального повреждения пакета при загрузке, заканчивая системой безопасности, которая блокирует установку.

Устранить ее можно самыми разными способами (какой сработает у вас, предугадать сложно):

• Для начала проверьте совместимость приложения с версией вашей ОС (в настройках перейдите в раздел «О телефоне», где и указана версия, в описании приложения также указывается требуемая версия ОС).
• При скачивании программ не из Google Play на устройстве Андроид должна быть разрешена установка из неизвестных источников (в настройках устройства перейдите в раздел «Безопасность», где требуется поставить галочку напротив «Неизвестные источники»).
• Перекачайте приложение. Возможно, в процессе загрузки был поврежден установочный пакет. Повторную загрузку производите с другого ресурса.
• Отключите антивирус, если он установлен. Для этого:

1. Откройте раздел «Приложения» в настройках
2. Найдите в списке ваш антивирус
3. Нажмите кнопку «Принудительно остановить» и «Отключить»

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

Обязательно сделайте копию нужных файлов!

Ошибка 110 при установке приложения на Андроид

Ошибка Android , которая актуальна все чаще. Сталкиваются с ней, как правило, пользователи, которые перешли на сторонние прошивки. Как исправить? В большинстве случаев выходом становится установка приложения из стороннего источника (меньше возни). Часто помогает обновление Google Play , также действенным считается очистка приложений, которые относятся к сервисам Google .