коды ошибок rest api
Коды ответа HTTP
Код ответа (состояния) HTTP показывает, был ли успешно выполнен определённый HTTP запрос. Коды сгруппированы в 5 классов:
Если вы получили код ответа (состояния), которого нет в данном списке, в таком случае он является не стандартизированным кодом ответа (состояния), вероятней всего он кастомный сервера.
Следующая таблица содержит список всех кодов и их значения:
Этот ответ отсылается, когда веб сервер после выполнения server-driven content negotiation, не нашёл контента, отвечающего критериям, полученным из user agent.
Этот ответ отсылается, когда запрос конфликтует с текущим состоянием сервера.
Этот ответ отсылается, когда запрашиваемый контент удалён с сервера.
Размер запроса превышает лимит, объявленный сервером. Сервер может закрыть соединение, вернув заголовок Retry-After
Коды ошибок REST API для партнеров
Ошибки в интерфейсах REST API партнеров возвращаются с использованием стандартных кодов состояния HTTP, а также объекта ответа JSON с ошибкой.
Коды состояния HTTP
В представленной ниже таблице перечислены и описаны коды состояния HTTP, которые могут быть возвращены этими интерфейсами.
| Код состояния | Сообщение о состоянии | Описание |
|---|---|---|
| 400 | Неверный запрос | Не удалось обработать запрос, так как он представлен в неправильном формате или является некорректным. |
| 401 | Не санкционировано | Необходимые данные для проверки подлинности отсутствуют или не являются допустимыми для ресурса. |
| 403 | Запрещено | Отказано в доступе к запрашиваемому ресурсу. Возможно, у пользователя недостаточно разрешений. Внимание! Код состояния HTTP 403; Forbidden error=insufficent_claims может возвращаться, если к ресурсу применены политики условного доступа. Дополнительные сведения о Microsoft Graph и условном доступе см. в статье Руководство разработчика по условному доступу в Azure Active Directory. |
| 404 | Не найдено | Запрашиваемый ресурс не существует. |
| 405 | Метод не разрешен | Метод HTTP в запросе не разрешено использовать для ресурса. |
| 406 | Недопустимо | Эта служба не поддерживает формат, запрашиваемый в заголовке Accept. |
| 409 | Конфликт | Текущее состояние конфликтует с ожиданиями запроса. Например, указанная родительская папка не существует. |
| 410 | Потеряно | Запрошенный ресурс больше не доступен на сервере. |
| 411 | Требуется длина | В запросе необходимо указать заголовок Content-Length. |
| 412 | Необходимое условие не выполнено | Необходимое условие, указанное в запросе (например, заголовок if-match), не соответствует текущему состоянию ресурса. |
| 413 | Слишком большой объект запроса | Размер запроса превышает ограничение. |
| 415 | Неподдерживаемый тип носителя | Тип контента запроса не поддерживается службой. |
| 416 | Запрошенный диапазон невыполним | Заданный диапазон байтов недопустим или недоступен. |
| 422 | Необрабатываемый объект | Не удалось обработать запрос, так как он является семантически некорректным. |
| 423 | Заблокировано | Запрашиваемый ресурс заблокирован. |
| 429 | Слишком много запросов | Клиентское приложение было отрегулировано, и ему не следует пытаться повторить запрос, пока не пройдет определенное время. |
| 500 | Внутренняя ошибка сервера | При обработке запроса возникла внутренняя ошибка сервера. |
| 501 | Не реализовано | Запрашиваемая функция не реализована. |
| 503 | Служба недоступна | Служба временно недоступна для обслуживания или перегружена. Вы можете повторить запрос по прошествии времени, которое можно указать в заголовке Retry-After. |
| 504 | Истекло время ожидания шлюза | Сервер, работающий в качестве прокси-сервера, при попытке выполнить запрос не получил своевременный ответ, необходимый для доступа, от сервера, находящегося выше в иерархии. Может возникать вместе с ошибкой 503. |
| 507 | Недостаточно места в хранилище | Достигнута максимальная квота хранилища. |
| 509 | Превышен предел пропускной способности | Приложение было отрегулировано из-за превышения максимальной пропускной способности. Приложение может повторить запрос по прошествии дополнительного времени. |
Ответ об ошибке — это отдельный объект JSON, содержащий одно свойство с именем error. Этот объект содержит все сведения об ошибке. Вы можете использовать возвращаемые в нем данные вместо кода состояния HTTP или вместе с ним. Ниже представлен пример полного текста ошибки JSON.
Тип ресурса ошибки
Ответ об ошибке — это отдельный объект JSON, содержащий одно свойство с именем error. Этот объект содержит все сведения об ошибке. Вы можете использовать возвращаемые в нем данные вместо кода состояния HTTP или вместе с ним. Ниже представлен пример полного текста ошибки JSON.
В приведенных ниже таблице и примере кода описывается схема ответа об ошибке.
| Имя | Тип | Описание |
|---|---|---|
| code | string | Всегда возвращается. Указывает тип возникшей ошибки. Не принимает значение null. |
| message | string | Всегда возвращается. Содержит подробное описание ошибки и дополнительные сведения для отладки. Не принимает значение null, не может быть пустым. Максимальная длина: 1024 символа. |
| innerError | object | Необязательно. Дополнительный объект ошибки, который может быть более подробным, чем ошибка верхнего уровня. |
| target | string | Целевой объект, в котором возникла ошибка. |
Свойство Code
Свойство code содержит одно из перечисленных ниже возможных значений. Приложения должны быть готовы к обработке любой из этих ошибок.
| Код | Описание |
|---|---|
| accessDenied | У вызывающей стороны нет разрешения на выполнение действия. |
| generalException | Возникла неопределенная ошибка. |
| invalidRequest | Запрос представлен в неправильном формате или является некорректным. |
| itemNotFound | Ресурс не найден. |
| preconditionFailed | Необходимое условие, указанное в запросе (например, заголовок if-match), не соответствует текущему состоянию ресурса. |
| resourceModified | Обновляемый ресурс изменился с момента последнего считывания. Как правило, это связано с несовпадением eTag. |
| serviceNotAvailable | Служба недоступна. Повторите попытку через некоторое время. Возможно, задан заголовок Retry-After. |
| unauthenticated | Вызывающий объект не прошел проверку подлинности. |
Объект InnerError
Объект innererror может рекурсивно содержать другие объекты innererror с дополнительными, более конкретными кодами ошибок. При обработке ошибки приложения должны циклически просматривать все доступные коды ошибок и использовать наиболее подробный из них, который понятен приложению.
REST страсти по 200
Давно я хотел написать эту статью. Все думал — с какой стороны зайти правильнее? Но, вдруг, недавно, на Хабре появилась подобная статья, которая вызвала бурю в стакане. Больше всего меня удивил тот факт, что статью начали вбивать в минуса, хотя она даже не декларировала что-то, а скорее поднимала вопрос об использовании кодов ответа web-сервера в REST. Дебаты разгорелись жаркие. А апофеозом стало то, что статья ушла в черновики… килобайты комментариев, мнений и т.д. просто исчезли. Многие стали кармо-жертвами, считай, ни за что 🙂
В общем, именно судьба той статьи побудила меня написать эту. И я очень надеюсь, что она будет полезна и прояснит многое.
Предупреждаю, все ниже написанное является реальным опытом, а не когнитивной эквилибристикой. И так, погнали.
Первым делом нужно очень четко разделить слои. Слой транспорта — http. Ну и собственно REST. Это фундаментально важная вещь в принятии всего и “себя” в нем. Давайте сначала поговорим только о http.
Я использовал термин “слой транспорта”. И я не оговорился. Все дело в том, что сам http реализует функции транспортировки запросов к серверу и контента к клиенту независимо от tcp/ip. Да, он базируется на tcp/ip. И вроде, нужно считать именно его транспортным. Но, нет. И вот почему — сокет-соединения не являются прямыми, т.е. это не соединение клиент-сервер. Как http запрос, так и http ответ могут пройти длинный путь через уйму сервисов. Могут быть агрегированы или напротив декомпозированы. Могут кэшироваться, могут модифицироваться.
Т.е. у http запроса как и http ответа есть свой маршрут. И он не зависит ни от конечного бэка, ни от конечного фронта. Прошу на это обратить особое внимание.
Маршруты http не являются статическими. Они могут быть очень сложными. Например, если в инфраструктуру встроен балансировщик, полученные запросы он может отправить на любую из нод бэка. При этом, сам бэк может реализовывать собственную стратегию работы с запросами. Часть из них пойдет на микросервисы напрямую, часть будет обработана самим web-сервером, часть дополнена и передана кому-то еще, а часть выдана из кэша и т.п. Так работает Интернет. Ничего нового.
И тут важно понять — зачем нам коды ответов? Все дело в том, что вся вышеописанная модель принимает решения на их базе. Т.е. это коды, позволяющие принимать инфраструктурные и транспортные решения в ходе маршрутизации http.
К примеру, если балансировщик встретится с кодом ответа от бэка 503, при передаче запроса, он может принять это за основание считать, что нода временно недоступна. Отмечу, что в ответе с кодом 503 предусмотрен заголовок Retry-After. Получив из заголовка интервал для повторного опроса, балансировщик оставит ноду в покое на указанный срок и будет работать с доступными. Причем, подобные стратегии реализуются “из коробки” web-серверами.
Небольшой офтопик для глубины понимания — а если нода ответила 500? Что должен сделать балансировщик? Переключать на другую? И многие ответят — конечно, все 5xx основание для отключение ноды. И будут неправы. Код 500 это код неожиданной ошибки. Т.е. той, которая может больше никогда и не повториться. И главное, что переключение на другую ноду может ничего и не изменить. Т.е. мы просто отключаем ноды без малейшей пользы.
В случае с 500 нам на помощь приходит статистика. Локальный WEB-сервер ноды, может переводить саму ноду в статус недоступности при большом количестве ответов 500. В этом случае, балансировщик обратившись на эту ноду, получит ответ 503 и не будет ее трогать. Результат тотже, но теперь, такое решение осмысленно и исключает “ложные” срабатывания.
Но и это еще не все. В такой ситуации мониторинг позволит админам подключиться к ситуации для обслуживания ноды. Т.е. мы получаем не просто реализацию высокодоступного сервиса, с балансировками и т.п., но еще и эффективный процесс поддержки.
И все это позволяют делать коды ответа сервера. Любая архитектура WEB-приложения должна начинаться с проектирования транспортного слоя. Надеюсь, сомнений в этом не осталось.
Задам риторический вопрос — что это такое? И что вы ответили себе на него? Не буду давать ссылки на очевидные пруфы, но скорее всего не совсем то, чем он является по сути 🙂 Это лишь идеология, стиль. Некие соображения на тему — как лучше общаться с бэком. И не просто общаться, а общаться в WEB инфраструктуре. Т.е. на базе http. Со всеми теми “полезными штуками”, о которых я написал выше. Конечные решения по реализации вашего интерфейса остаются всегда за вами.
Вы задумывались почему не придуман отдельный транспорт для REST? Например, для websocket он есть. Да, он тоже начинается с http, но потом, после установки соединения, это вообще отдельная песня. Почему бы не сделать такую же для REST?
Ответ прост — а зачем? Есть прекрасный, уже готовый, выверенный протокол — http. Он хорошо масштабируется. Позволяет реализовывать сложные, высокодоступные сервисы, способные справляться с большой нагрузкой. Все, что нужно — ввести некие концептуальные правила, чтобы разработчики друг друга понимали.
Отсюда следует простой, очевидный вывод — все, что присуще http, присуще и REST. Это неотделимые сущности. Нет отдельного заголовка REST, нет даже намека на то, что REST это REST. Для любого сервера REST запрос ровно такой же, как и любой другой. Т.е. REST это только то, что у нас “в голове”.
Коды ответа http в REST
Давайте поговорим о том, каким же кодом должен отвечать ваш сервер на REST запрос? Лично мне кажется, что из всего выше написанного уже очевиден ответ, что т.к. REST не отличается от любого другого запроса, он должен быть подчинен ровно тем же правилам. Код ответа — неотъемлемая часть REST и он должен быть релевантен сути ответа. Т.е. если не найден объект по запросу, это 404, если клиент обратился с некорректным запросом 400 и т.д. Но, чаще всего, дебаты на сём не заканчиваются. Поэтому, продолжу и я.
Можно ли отвечать на всё кодом 200? А кто вам запретит? Пожалуйста… код 200 такой же код как и другие. Правда, в основе такого подхода лежит очень простой тезис — моя система идеальная, у нее не бывает ошибок. Если вы человек, который может создавать такие системы — этому можно только позавидовать!
Но скорее всего… она не идеальна. И ошибки все же случаются. А бывает, что они случаются по независящим от нас обстоятельствам. И тут типовым решением является создание собственной системы кодирования ошибок. Это плохо? Да, это плохо. Это супер-плохо. Давайте разбираться почему.
И так, принимая код 200 как единственно верный, мы берем на себя обязанности на разработку целого слоя (критического слоя) системы — обработку ошибок. Т.е. труд многих людей по разработке этого слоя отправляется в утиль. И начинается постройка своего “велосипеда”. Но эта мегастройка обречена на провал.
Начнем с кода. Если мы собираемся на все отвечать 200, нам самим придется обрабатывать ошибки. Классическим методом является try конструкции. Каждый сегмент кода мы оборачиваем дополнительным кодом. Обработчиками, которые что-то делают полезное. Например, что-то кладут в лог. Что-то важное. Что позволит локализовать ошибку. А если ошибка возникла не там где ее ожидали? Или если ошибка возникла в обработчике ошибки? Т.е. эта стратегия на уровне кода нерабочая априори. И в конце концов, обрабатывать ваши баги будет интерпретатор или платформа. ОС, наконец. Суть бага в том, что вы его не ждете. Не нужно его прятать, его нужно находить и фиксить. Поэтому, если на какие-то запросы REST ответит ошибкой 500 это нормально. И более того — правильно.
Давайте еще раз вернемся к вопросу — почему это правильно? Потому что:
7. Даже если вы очень сильно постараетесь избежать иных кодов ответа от сервера кроме как 200 на ваши запросы, вы не сможете это сделать. Вам может ответить на ваш запрос любой сервер посредник, совершенно любым кодом. И вы ДОЛЖНЫ будете такой ответ обработать корректно.
Итого, на логическом уровне борьба за код 200 бессмысленна.
Теперь давайте вернемся к инфраструктурному уровню. Очень часто слышу мнение — код 5xx не прикладного уровня, его нельзя отдавать бэком. Кхм, ну… тут есть противоречие в самом утверждении. Отдавать можно. Но код этот не прикладного уровня. Вот так вернее. Для понимания этого, предлагаю рассмотреть кейс:
Вы реализуете шлюз. У вас несколько ДЦ, на каждом свой канал связи к некоему приватному сервису. Ну, к примеру, к платежке по VPN. И есть канал коммуникации с Интернет. Вы получаете запрос на операцию со шлюзом, но… сервис оказывается недоступен.
И так, что вы должны ответить? Кому? Это проблема именно инфраструктурная и, именно, бэк столкнулся с ней. Конечно, нужно смело отвечать 503. Эти действия приведут к тому, что нода будет отключена балансировщиком на какое-то время. При этом, балансировщик при правильной настройке, не разрывая соединение с клиентом, отправит запрос в другую ноду. И… конечный клиент, с великой долей вероятности получил 200. А не кастомное описание ошибки, которая ему ничем не поможет.
Где и какой код использовать
Вопрос непростой. На него нет однозначного ответа. Для каждой системы проектируется транспортный слой и коды в нем могут быть специфичные.
Есть принятые стандарты. Их можно легко найти и, опять же, не буду очевидные пруфы приводить. Но, приведу неочевидный — developer.mozilla.org/ru/docs/Web/HTTP/Status
Почему его? Все дело в том, что обработчики кода могут вести себя по разному, в зависимости от реализации и контекста “понимания кода”. К примеру, в браузерах есть стратегия кеширования, завязанная на коды ответа. А в некоторых сервисах есть свои, кастомные коды. Например, CloudFlare.
Т.е. принятие решений об использовании кодов, нужно базировать на всех элементах входящих в транспортный слой от вашего кода на бэке до кода на клиенте. Только так можно найти верные ответы. Я даже пытаться тут дать всем универсальную пилюлю не буду.
Корни зла
Уже третий проект, в который я прихожу страдает кодом 200 в REST. Именно страдает. Другого слова нет. Если вы внимательно прочли всё до текущего момента, вы уже понимаете, что как только проект начинает расти, у него появляется потребность в развитии инфраструктуры, в ее устойчивости. Код 200 убивает все эти потуги на корню. И первое, что приходится делать — ломать стереотипы.
Корень зла, мне кажется лежит в том, что код 500, это первое, что web-разработчик встречает в своей профессиональной деятельности. Это, можно сказать, детская травма. И все его старания поначалу сводятся к тому, чтобы получить код 200.
Кстати, по какой-то причине, на этом же этапе развивается устойчивое мнение, что только ответы с кодом 200 могут быть снабжены телом. Конечно, это не так и с любым кодом может “приехать” любой ответ. Код это код. Тело это тело.
Далее, с развитием разработчика, у него возникают потребности в управлении багами собственного приложения. Но…, он не умеет пользоваться логами. Не умеет настраивать web-сервер. Он учится. И рождаются те самые «велики». Потому что, они ему доступны и он может их быстро сделать. Далее, на этот «велик» он монтирует новые колеса, усиливает раму и т.д. И этот велик становится его спутником на достаточно длительный промежуток времени, пока… пока у него не появляются реально сложные, многокомпонентные задачи. И тут, как говорится — вход в супермаркет с «великами» и на роликах запрещен.
Коды ответов REST API
REST API использует строку состояния в HTTP ответе (статус ответа), чтобы информировать Клиентов о результате запроса.
HTTP определяет 40 стандартных кодов состояния (статусов ответа), которые делятся на пять категорий. Ниже выделены только те коды состояния, которые используются в REST API.
| Категория | Описание |
|---|---|
| 2xx: Успех | Этот класс кодов состояния указывает, что запрос клиента был успешно получен, понят, и принят. |
| 3xx: Перенаправление | Коды этого класса сообщают клиенту, что для успешного выполнения операции необходимо сделать другой запрос, как правило, по другому URI. Из данного класса пять кодов 301, 302, 303, 305 и 307 относятся непосредственно к перенаправлениям. |
| 4xx: Ошибка клиента | Класс кодов 4xx предназначен для указания ошибок со стороны клиента. |
| 5xx: Ошибка сервера | Коды ответов, начинающиеся с «5» указывают на случаи, когда сервер знает, что произошла ошибка или он не может обработать запрос. |
Коды состояний в REST
200 (OK)
Запрос выполнен успешно. Информация, возвращаемая с ответом зависит от метода, используемого в запросе, например при:
REST API отвечает кодом состояния 201 при каждом создании ресурса в коллекции. Также могут быть случаи, когда новый ресурс создается в результате какого-либо действия контроллера, и в этом случае 201 также будет подходящем ответом.
Ссылка (URL) на новый ресурс может быть в теле ответа или в поле заголовка ответа Location.
Сервер должен создать ресурс перед тем как вернуть 201 статус. Если это невозможно сделать сразу, тогда сервер должен ответить кодом 202 (Accepted).
Ответ 202 обычно используется для действий, которые занимают много времени для обработки и не могут быть выполнены сразу. Это означает, что запрос принят к обработке, но обработка не завершена.
Его цель состоит в том, чтобы позволить серверу принять запрос на какой-либо другой процесс (возможно, пакетный процесс, который выполняется только один раз в день), не требуя, чтобы соединение агента пользователя с сервером сохранялось до тех пор, пока процесс не будет завершен.
Сущность, возвращаемая с этим ответом, должна содержать указание на текущее состояние запроса и указатель на монитор состояния (расположение очереди заданий) или некоторую оценку того, когда пользователь может ожидать выполнения запроса.
Код состояния 204 обычно отправляется в ответ на запрос PUT, POST или DELETE, когда REST API отказывается отправлять обратно любое сообщение о состоянии проделанной работы.
API может также отправить 204 статус в ответ на GET запрос, чтобы указать, что запрошенный ресурс существует, но не имеет данных для добавления их в тело ответа.
Ответ 204 не должен содержать тело сообщения и, таким образом, всегда завершается первой пустой строкой после полей заголовка.
Вы вряд ли будете использовать этот код ответа в своем API, так как вы всегда можете использовать версию API для нового API, сохраняя при этом старый.
Является распространенным способом выполнить перенаправление на другой URL. HTTP-ответ с этим кодом должен дополнительно предоставит URL-адрес куда перенаправлять в поле заголовка Location. Агенту пользователя (например, браузеру) предлагается в ответе с этим кодом сделать второй запрос на новый URL.
Многие браузеры реализовали этот код таким образом, что нарушили стандарт. Они начали изменять Тип исходного запроса, например с POST на GET. Коды состояния 303 и 307 были добавлены для серверов, которые хотят однозначно определить, какая реакция ожидается от клиента.
Ответ 303 указывает, что ресурс контроллера завершил свою работу, но вместо отправки нежелательного тела ответа он отправляет клиенту URI ресурса. Это может быть URI временного сообщения о состоянии ресурса или URI для уже существующего постоянного ресурса.
Ответ 303 не должен кэшироваться, но ответ на второй (перенаправленный) запрос может быть кэшируемым.
В таком случае нет необходимости повторно передавать ресурс, так как у клиента все еще есть ранее загруженная копия.
Все это экономит ресурсы клиента и сервера, так как только заголовки должны быть отправлены и приняты, и серверу нет необходимости генерировать контент снова, а клиенту его получать.
Rest API может использовать этот код состояния для назначения временного URL запрашиваемому ресурсу.
Если метод запроса не HEAD, тело ответа должно содержать короткую заметку с гиперссылкой на новый URL. Если код 307 был получен в ответ на запрос, отличный от GET или HEAD, Клиент не должен автоматически перенаправлять запрос, если он не может быть подтвержден Клиентом, так как это может изменить условия, при которых был создан запрос.
Это общий статус ошибки на стороне Клиента. Используется, когда никакой другой код ошибки 4xx не уместен. Ошибки могут быть как неправильный синтаксис запроса, неверные параметры запроса, запросы вводящие в заблуждение или маршрутизатор и т.д.
Клиент не должен повторять точно такой же запрос.
Клиент может повторить запрос указав в заголовке подходящее поле авторизации. Если это уже было сделано, то в ответе 401 будет указано, что авторизация для указанных учетных данных не работает. Если в ответе 401 содержится та же проблема, что и в предыдущем ответе, и Клиент уже предпринял хотя бы одну попытку проверки подлинности, то пользователю Клиента следует представить данные полученные в ответе, владельцу сайта, так как они могут помочь в диагностике проблемы.
Ошибка 403 указывает, что rest API отказывается выполнять запрос клиента, т.е. Клиент не имеет необходимых разрешений для доступа. Ответ 403 не является случаем, когда нужна авторизация (для ошибки авторизации используется код 401).
Попытка аутентификация не поможет, и повторные запросы не имеют смысла.
Указывает, что rest API не может сопоставить URL клиента с ресурсом, но этот URL может быть доступен в будущем. Последующие запросы клиента допустимы.
API выдает ошибку 405, когда клиент пытался использовать HTTP метод, который недопустим для ресурса. Например, указан метод PUT, но такого метода у ресурса нет.
В таких случаях Клиент должен решить проблему данных у себя и только потом отправлять запросы повторно.
Когда клиент указывает rest API выполнять запрос только при выполнении определенных условий, а API не может выполнить запрос при таких условиях, то возвращается ответ 412.
Ошибка 500 никогда не является клиента, и поэтому для клиента разумно повторить точно такой же запрос, который инициировал этот ответ, и надеяться что в этот раз сервер отработает без ошибок.
Сервер не распознает метод запроса и не имеет возможности исполнить просьбу клиента. Обычно это подразумевает будущую доступность (например, новая функция API веб-сервиса).