REST API использует строку состояния в HTTP ответе (статус ответа), чтобы информировать Клиентов о результате запроса.
Вообще HTTP определяет 40 стандартных кодов состояния (статусов ответа), которые делятся на пять категорий. Ниже выделены только те коды состояния, которые часто используются в REST API.
| Категория | Описание |
|---|---|
| 1xx: Информация | В этот класс содержит заголовки информирующие о процессе передачи. Это обычно предварительный ответ, состоящий только из Status-Line и опциональных заголовков, и завершается пустой строкой. Нет обязательных заголовков. Серверы НЕ ДОЛЖНЫ посылать 1xx ответы HTTP/1.0 клиентам. |
| 2xx: Успех | Этот класс кодов состояния указывает, что запрос клиента был успешно получен, понят, и принят. |
| 3xx: Перенаправление | Коды этого класса сообщают клиенту, что для успешного выполнения операции необходимо сделать другой запрос, как правило, по другому URI. Из данного класса пять кодов 301, 302, 303, 305 и 307 относятся непосредственно к перенаправлениям. |
| 4xx: Ошибка клиента | Класс кодов 4xx предназначен для указания ошибок со стороны клиента. |
| 5xx: Ошибка сервера | Коды ответов, начинающиеся с «5» указывают на случаи, когда сервер знает, что произошла ошибка или он не может обработать запрос. |
Коды состояний в REST
Звездочкой * помечены популярные (часто используемые) коды ответов.
200 * (OK)
Запрос выполнен успешно. Информация, возвращаемая с ответом зависит от метода, используемого в запросе, например при:
- GET Получен объект, соответствующий запрошенному ресурсу.
- HEAD Получены поля заголовков, соответствующие запрошенному ресурсу, тело ответа пустое.
- POST Запрошенное действие выполнено.
201 * (Created — Создано)
REST API отвечает кодом состояния 201 при каждом создании ресурса в коллекции. Также могут быть случаи, когда новый ресурс создается в результате какого-либо действия контроллера, и в этом случае 201 также будет подходящем ответом.
Ссылка (URL) на новый ресурс может быть в теле ответа или в поле заголовка ответа Location.
Сервер должен создать ресурс перед тем как вернуть 201 статус. Если это невозможно сделать сразу, тогда сервер должен ответить кодом 202 (Accepted).
202 (Accepted — Принято)
Ответ 202 обычно используется для действий, которые занимают много времени для обработки и не могут быть выполнены сразу. Это означает, что запрос принят к обработке, но обработка не завершена.
Его цель состоит в том, чтобы позволить серверу принять запрос на какой-либо другой процесс (возможно, пакетный процесс, который выполняется только один раз в день), не требуя, чтобы соединение агента пользователя с сервером сохранялось до тех пор, пока процесс не будет завершен.
Сущность, возвращаемая с этим ответом, должна содержать указание на текущее состояние запроса и указатель на монитор состояния (расположение очереди заданий) или некоторую оценку того, когда пользователь может ожидать выполнения запроса.
203 (Non-Authoritative Information — Неавторитетная информация)
Предоставленная информация взята не из оригинального источника (а, например, из кэша, который мог устареть, или из резервной копии, которая могла потерять актуальность). Этот факт отражен в заголовке ответа и подтверждается этим кодом. Предоставленная информация может совпадать, а может и не совпадать с оригинальными данными.
204 * (No Content — Нет контента)
Код состояния 204 обычно отправляется в ответ на запрос PUT, POST или DELETE, когда REST API отказывается отправлять обратно любое сообщение о состоянии проделанной работы.
API может также отправить 204 статус в ответ на GET запрос, чтобы указать, что запрошенный ресурс существует, но не имеет данных для добавления их в тело ответа.
Ответ 204 не должен содержать тело сообщения и, таким образом, всегда завершается первой пустой строкой после полей заголовка.
205 — (Reset Content — Сброшенное содержимое)
Сервер успешно обработал запрос и обязывает клиента сбросить введенные пользователем данные. В ответе не должно передаваться никаких данных (в теле ответа). Обычно применяется для возврата в начальное состояние формы ввода данных на клиенте.
206 — (Partial Content — Частичное содержимое)
Сервер выполнил часть GET запроса ресурса. Запрос ДОЛЖЕН был содержать поле заголовка Range (секция 14.35), который указывает на желаемый диапазон и МОГ содержать поле заголовка If-Range (секция 14.27), который делает запрос условным.
Запрос ДОЛЖЕН содержать следующие поля заголовка:
- Либо поле Content-Range (секция 14.16), который показывает диапазон, включённый в этот запрос, либо Content-Type со значением multipart/byteranges, включающими в себя поля Content-Range для каждой части. Если в заголовке запроса есть поле Content-Length, его значение ДОЛЖНО совпадать с фактическим количеством октетов, переданных в теле сообщения.
- Date
- ETag и/или Content-Location, если ранее был получен ответ 200 на такой же запрос.
- Expires, Cache-Control, и/или Vary, если значение поля изменилось с момента отправления последнего такого же запроса
Если ответ 206 — это результат выполнения условного запроса, который использовал строгий кэш-валидатор (подробнее в секции 13.3.3), в ответ НЕ СЛЕДУЕТ включать какие-либо другие заголовки сущности. Если такой ответ — результат выполнения запроса If-Range, который использовал «слабый» валидатор, то ответ НЕ ДОЛЖЕН содержать другие заголовки сущности; это предотвращает несоответствие между закэшированными телами сущностей и обновлёнными заголовками. В противном случае ответ ДОЛЖЕН содержать все заголовки сущностей, которые вернули статус 200 (OK) на тот же запрос.
Кэш НЕ ДОЛЖЕН объединять ответ 206 с другими ранее закэшированными данными, если поле ETag или Last-Modified в точности не совпадают (подробнее в секции 16.5.4)
Кэш, который не поддерживает заголовки Range и Content-Range НЕ ДОЛЖЕН кэшировать ответы 206 (Partial).
300 — (Multiple Choices — Несколько вариантов)
По указанному URI существует несколько вариантов предоставления ресурса по типу MIME, по языку или по другим характеристикам. Сервер передаёт с сообщением список альтернатив, давая возможность сделать выбор клиенту автоматически или пользователю.
Если это не запрос HEAD, ответ ДОЛЖЕН включать объект, содержащий список характеристик и адресов, из которого пользователь или агент пользователя может выбрать один наиболее подходящий. Формат объекта определяется по типу данных приведённых в Content-Type поля заголовка. В зависимости от формата и возможностей агента пользователя, выбор наиболее подходящего варианта может выполняться автоматически. Однако эта спецификация не определяет никакого стандарта для автоматического выбора.
Если у сервера есть предпочтительный выбор представления, он ДОЛЖЕН включить конкретный URI для этого представления в поле Location; агент пользователя МОЖЕТ использовать заголовок Location для автоматического перенаправления к предложенному ресурсу. Этот запрос может быть закэширован, если явно не было указано иного.
301 (Moved Permanently — Перемещено навсегда)
Код перенаправления. Указывает, что модель ресурсов REST API была сильно изменена и теперь имеет новый URL. Rest API должен указать новый URI в заголовке ответа Location, и все будущие запросы должны быть направлены на указанный URI.
Вы вряд ли будете использовать этот код ответа в своем API, так как вы всегда можете использовать версию API для нового API, сохраняя при этом старый.
302 (Found — Найдено)
Является распространенным способом выполнить перенаправление на другой URL. HTTP-ответ с этим кодом должен дополнительно предоставит URL-адрес куда перенаправлять в поле заголовка Location. Агенту пользователя (например, браузеру) предлагается в ответе с этим кодом сделать второй запрос на новый URL.
Многие браузеры реализовали этот код таким образом, что нарушили стандарт. Они начали изменять Тип исходного запроса, например с POST на GET. Коды состояния 303 и 307 были добавлены для серверов, которые хотят однозначно определить, какая реакция ожидается от клиента.
303 (See Other — Смотрите другое)
Ответ 303 указывает, что ресурс контроллера завершил свою работу, но вместо отправки нежелательного тела ответа он отправляет клиенту URI ресурса. Это может быть URI временного сообщения о состоянии ресурса или URI для уже существующего постоянного ресурса.
Код состояния 303 позволяет REST API указать ссылку на ресурс, не заставляя клиента загружать ответ. Вместо этого клиент может отправить GET запрос на URL указанный в заголовке Location.
Ответ 303 не должен кэшироваться, но ответ на второй (перенаправленный) запрос может быть кэшируемым.
304 * (Not Modified — Не изменен)
Этот код состояния похож на 204 (Нет контента), так как тело ответа должно быть пустым. Ключевое различие состоит в том, что 204 используется, когда нет ничего для отправки в теле, тогда как 304 используется, когда ресурс не был изменен с версии, указанной заголовками запроса If-Modified-Since или If-None-Match.
В таком случае нет необходимости повторно передавать ресурс, так как у клиента все еще есть ранее загруженная копия.
Все это экономит ресурсы клиента и сервера, так как только заголовки должны быть отправлены и приняты, и серверу нет необходимости генерировать контент снова, а клиенту его получать.
305 — (Use Proxy — Используйте прокси)
Доступ к запрошенному ресурсу ДОЛЖЕН быть осуществлен через прокси-сервер, указанный в поле Location. Поле Location предоставляет URI прокси. Ожидается, что получатель повторит этот запрос с помощью прокси. Ответ 305 может генерироваться ТОЛЬКО серверами-источниками.
Заметьте: в спецификации RFC 2068 однозначно не сказано, что ответ 305 предназначен для перенаправления единственного запроса, и что он должен генерироваться только сервером-источником. Упущение этих ограничений вызвало ряд значительных последствий для безопасности.
Многие HTTP клиенты (такие, как Mozilla и Internet Explorer) обрабатывают этот статус некорректно прежде всего из соображений безопасности.
307 (Temporary Redirect — Временный редирект)
Ответ 307 указывает, что rest API не будет обрабатывать запрос клиента. Вместо этого клиент должен повторно отправить запрос на URL, указанный в заголовке Location. Однако в будущих запросах клиент по-прежнему должен использоваться исходный URL.
Rest API может использовать этот код состояния для назначения временного URL запрашиваемому ресурсу.
Если метод запроса не HEAD, тело ответа должно содержать короткую заметку с гиперссылкой на новый URL. Если код 307 был получен в ответ на запрос, отличный от GET или HEAD, Клиент не должен автоматически перенаправлять запрос, если он не может быть подтвержден Клиентом, так как это может изменить условия, при которых был создан запрос.
308 — (Permanent Redirect — Постоянное перенаправление) (experimental)
Нужно повторить запрос на другой адрес без изменения применяемого метода.
Этот и все последующие запросы нужно повторить на другой URI. 307 и 308 (как предложено) Схож в поведении с 302 и 301, но не требуют замены HTTP метода. Таким образом, например, отправку формы на «постоянно перенаправленный» ресурс можно продолжать без проблем.
400 * (Bad Request — Плохой запрос)
Это общий статус ошибки на стороне Клиента. Используется, когда никакой другой код ошибки 4xx не уместен. Ошибки могут быть как неправильный синтаксис запроса, неверные параметры запроса, запросы вводящие в заблуждение или маршрутизатор и т.д.
Клиент не должен повторять точно такой же запрос.
401 * (Unauthorized — Неавторизован)
401 сообщение об ошибке указывает, что клиент пытается работать с закрытым ресурсом без предоставления данных авторизации. Возможно, он предоставил неправильные учетные данные или вообще ничего. Ответ должен включать поле заголовка WWW-Authenticate, содержащего описание проблемы.
Клиент может повторить запрос указав в заголовке подходящее поле авторизации. Если это уже было сделано, то в ответе 401 будет указано, что авторизация для указанных учетных данных не работает. Если в ответе 401 содержится та же проблема, что и в предыдущем ответе, и Клиент уже предпринял хотя бы одну попытку проверки подлинности, то пользователю Клиента следует представить данные полученные в ответе, владельцу сайта, так как они могут помочь в диагностике проблемы.
402 — (Payment Required — Требуется оплата)
Этот код зарезервирован для использования в будущем.
Предполагается использовать в будущем. В настоящий момент не используется. Этот код предусмотрен для платных пользовательских сервисов, а не для хостинговых компаний. Имеется в виду, что эта ошибка не будет выдана хостинговым провайдером в случае просроченной оплаты его услуг. Зарезервирован, начиная с HTTP/1.1.
403 * (Forbidden — Запрещено)
Ошибка 403 указывает, что rest API отказывается выполнять запрос клиента, т.е. Клиент не имеет необходимых разрешений для доступа. Ответ 403 не является случаем, когда нужна авторизация (для ошибки авторизации используется код 401).
Попытка аутентификация не поможет, и повторные запросы не имеют смысла.
404 * (Not Found — Не найдено)
Указывает, что rest API не может сопоставить URL клиента с ресурсом, но этот URL может быть доступен в будущем. Последующие запросы клиента допустимы.
404 не указывает, является ли состояние временным или постоянным. Для указания постоянного состояния используется код 410 (Gone — Пропал). 410 использоваться, если сервер знает, что старый ресурс постоянно недоступен и более не имеет адреса.
405 (Method Not Allowed — Метод не разрешен)
API выдает ошибку 405, когда клиент пытался использовать HTTP метод, который недопустим для ресурса. Например, указан метод PUT, но такого метода у ресурса нет.
Ответ 405 должен включать Заголовок Allow, в котором перечислены поддерживаемые HTTP методы, например, Allow: GET, POST.
406 (Not Acceptable — Неприемлемый)
API не может генерировать предпочитаемые клиентом типы данных, которые указаны в заголовке запроса Accept. Например, запрос клиента на данные в формате application/xml получит ответ 406, если API умеет отдавать данные только в формате application/json.
В таких случаях Клиент должен решить проблему данных у себя и только потом отправлять запросы повторно.
407 — (Proxy Authentication Required — Требуется прокси-аутентификация)
Ответ аналогичен коду 401, за исключением того, что аутентификация производится для прокси-сервера. Механизм аналогичен идентификации на исходном сервере.
Пользователь должен сначала авторизоваться через прокси. Прокси-сервер должен вернуть Proxy-Authenticate заголовок, содержащий запрос ресурса. Клиент может повторить запрос вместе с Proxy-Authenticate заголовком. Появился в HTTP/1.1.
408 — (Request Timeout — Таймаут запроса)
Время ожидания сервером передачи от клиента истекло. Клиент не предоставил запрос за то время, пока сервер был готов его принят. Клиент МОЖЕТ повторить запрос без изменений в любое время.
Например, такая ситуация может возникнуть при загрузке на сервер объёмного файла методом POST или PUT. В какой-то момент передачи источник данных перестал отвечать, например, из-за повреждения компакт-диска или потери связи с другим компьютером в локальной сети. Пока клиент ничего не передаёт, ожидая от него ответа, соединение с сервером держится. Через некоторое время сервер может закрыть соединение со своей стороны, чтобы дать возможность другим клиентам сделать запрос.
409 * (Conflict — Конфликт)
Запрос нельзя обработать из-за конфликта в текущем состоянии ресурса. Этот код разрешается использовать только в тех случаях, когда ожидается, что пользователь может самостоятельно разрешить этот конфликт и повторить запрос. В тело ответа СЛЕДУЕТ включить достаточное количество информации для того, чтобы пользователь смог понять причину конфликта. В идеале ответ должен содержать такую информацию, которая поможет пользователю или его агенту исправить проблему. Однако это не всегда возможно и это не обязательно.
Как правило, конфликты происходят во время PUT-запроса. Например, во время использования версионирования, если сущность, к которой обращаются методом PUT, содержит изменения, конфликтующие с теми, что были сделаны ранее третьей стороной, серверу следует использовать ответ 409, чтобы дать понять пользователю, что этот запрос нельзя завершить. В этом случае в ответной сущности должен содержаться список изменений между двумя версиями в формате, который указан в поле заголовка Content-Type.
410 — (Gone — Исчез)
Такой ответ сервер посылает, если ресурс раньше был по указанному URL, но был удалён и теперь недоступен. Серверу в этом случае неизвестно и местоположение альтернативного документа, например, копии. Если у сервера есть подозрение, что документ в ближайшее время может быть восстановлен, то лучше клиенту передать код 404. Появился в HTTP/1.1.
411 — (Length Required — Требуется длина)
Для указанного ресурса клиент должен указать Content-Length в заголовке запроса. Без указания этого поля не стоит делать повторную попытку запроса к серверу по данному URI. Такой ответ естественен для запросов типа POST и PUT. Например, если по указанному URI производится загрузка файлов, а на сервере стоит ограничение на их объём. Тогда разумней будет проверить в самом начале заголовок Content-Length и сразу отказать в загрузке, чем провоцировать бессмысленную нагрузку, разрывая соединение, когда клиент действительно пришлёт слишком объёмное сообщение.
412 — (Precondition Failed — Предварительное условие не выполнено)
Возвращается, если ни одно из условных полей заголовка запроса не было выполнено.
Когда клиент указывает rest API выполнять запрос только при выполнении определенных условий, а API не может выполнить запрос при таких условиях, то возвращается ответ 412.
Этот код ответа позволяет клиенту записывать предварительные условия в метаинформации текущего ресурса, таким образом, предотвращая применение запрошенного метода к ресурсу, кроме того, что ожидается.
413 — (Request Entity Too Large — Сущность запроса слишком большая)
Возвращается в случае, если сервер отказывается обработать запрос по причине слишком большого размера тела запроса. Сервер может закрыть соединение, чтобы прекратить дальнейшую передачу запроса.
Если проблема временная, то рекомендуется в ответ сервера включить заголовок Retry-After с указанием времени, по истечении которого можно повторить аналогичный запрос.
414 — (Request-URI Too Long — Запрос-URI Слишком длинный)
Сервер не может обработать запрос из-за слишком длинного указанного URL. Эту редкую ошибку можно спровоцировать, например, когда клиент пытается передать длинные параметры через метод GET, а не POST, когда клиент попадает в «чёрную дыру» перенаправлений (например, когда префикс URI указывает на своё же окончание), или когда сервер подвергается атаке со стороны клиента, который пытается использовать дыры в безопасности, которые встречаются на серверах с фиксированной длиной буфера для чтения или обработки Request-URI.
415 (Unsupported Media Type — Неподдерживаемый медиа тип)
Сообщение об ошибке 415 указывает, что API не может обработать предоставленный клиентом Тип медиа, как указано в заголовке запроса Content-Type.
Например, запрос клиента содержит данные в формате application/xml, а API готов обработать только application/json. В этом случае клиент получит ответ 415.
Например, клиент загружает изображение как image/svg+xml, но сервер требует, чтобы изображения использовали другой формат.
428 — (Precondition Required — Требуется предварительное условие)
Код состояния 428 указывает, что исходный сервер требует, чтобы запрос был условным.
Его типичное использование — избежать проблемы «потерянного обновления», когда клиент ПОЛУЧАЕТ состояние ресурса, изменяет его и ОТПРАВЛЯЕТ обратно на сервер, когда тем временем третья сторона изменила состояние на сервере, что привело к конфликту. Требуя, чтобы запросы были условными, сервер может гарантировать, что клиенты работают с правильными копиями.
Ответы с этим кодом состояния ДОЛЖНЫ объяснять, как повторно отправить запрос.
429 — (Too Many Requests — Слишком много запросов)
Пользователь отправил слишком много запросов за заданный промежуток времени.
Представления ответа ДОЛЖНЫ включать подробности, объясняющие условие, и МОГУТ включать заголовок Retry-After, указывающий, как долго ждать, прежде чем делать новый запрос.
431 — (Request Header Fields Too Large — Слишком большие поля заголовка запроса)
Код состояния 431 указывает на то, что сервер не желает обрабатывать запрос, поскольку его поля заголовка слишком велики. Запрос МОЖЕТ быть отправлен повторно после уменьшения размера полей заголовка запроса.
Его можно использовать как в случае, когда совокупность полей заголовка запроса слишком велика, так и в случае неисправности одного поля заголовка. В последнем случае представление ответа ДОЛЖНО указывать, какое поле заголовка было слишком большим.
444 — (No Response — Нет ответа) (Nginx)
Код ответа Nginx. Сервер не вернул информацию и закрыл соединение. (полезно в качестве сдерживающего фактора для вредоносных программ)
451 — (Unavailable For Legal Reasons — Недоступен по юридическим причинам)
Доступ к ресурсу закрыт по юридическим причинам. Наиболее близким из существующих является код 403 Forbidden (сервер понял запрос, но отказывается его обработать). Однако в случае цензуры, особенно когда это требование к провайдерам заблокировать доступ к сайту, сервер никак не мог понять запроса — он его даже не получил. Совершенно точно подходит другой код: 305 Use Proxy. Однако такое использование этого кода может не понравиться цензорам. Было предложено несколько вариантов для нового кода, включая «112 Emergency. Censorship in action» и «460 Blocked by Repressive Regime»
500 * (Internal Server Error — Внутренняя ошибка сервера)
Общий ответ при ошибке в коде. Универсальное сообщение о внутренней ошибке сервера, когда никакое более определенное сообщение не подходит.
Большинство веб-платформ автоматически отвечают этим кодом состояния, когда при выполнении кода обработчика запроса возникла ошибка.
Ошибка 500 никогда не зависит от клиента, поэтому для клиента разумно повторить точно такой же запрос, и надеяться что в этот раз сервер отработает без ошибок.
501 (Not Implemented — Не реализован)
Серверу либо неизвестен метод запроса, или ему (серверу) не хватает возможностей выполнить запрос. Обычно это подразумевает будущую доступность (например, новая функция API веб-сервиса).
Если же метод серверу известен, но он не применим к данному ресурсу, то нужно вернуть ответ 405.
502 — (Bad Gateway — Плохой шлюз)
Сервер, выступая в роли шлюза или прокси-сервера, получил некорректный ответ от вышестоящего сервера, к которому он обратился. Появился в HTTP/1.0.
503 — (Service Unavailable — Служба недоступна)
Сервер не может обработать запрос из-за временной перегрузки или технических работ. Это временное состояние, из которого сервер выйдет через какое-то время. Если это время известно, то его МОЖНО передать в заголовке Retry-After.
504 — (Gateway Timeout — Таймаут шлюза)
Сервер, в роли шлюза или прокси-сервера, не дождался в рамках установленного таймаута ответа от вышестоящего сервера текущего запроса.
505 — (HTTP Version Not Supported — Версия HTTP не поддерживается)
Сервер не поддерживает или отказывается поддерживать указанную в запросе версию протокола HTTP.
510 — (Not Extended — Не расширен)
В запросе не соблюдена политика доступа к ресурсу. Сервер должен отправить обратно всю информацию, необходимую клиенту для отправки расширенного запроса. Указание того, как расширения информируют клиента, выходит за рамки данной спецификации.
—
Источники и более подробная информация:
- https://restapitutorial.ru/httpstatuscodes.html
- https://www.restapitutorial.com/httpstatuscodes.html
- https://restfulapi.net/http-status-codes/
- https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/428
Время на прочтение
8 мин
Количество просмотров 40K
Давно я хотел написать эту статью. Все думал — с какой стороны зайти правильнее? Но, вдруг, недавно, на Хабре появилась подобная статья, которая вызвала бурю в стакане. Больше всего меня удивил тот факт, что статью начали вбивать в минуса, хотя она даже не декларировала что-то, а скорее поднимала вопрос об использовании кодов ответа web-сервера в REST. Дебаты разгорелись жаркие. А апофеозом стало то, что статья ушла в черновики… килобайты комментариев, мнений и т.д. просто исчезли. Многие стали кармо-жертвами, считай, ни за что 
В общем, именно судьба той статьи побудила меня написать эту. И я очень надеюсь, что она будет полезна и прояснит многое.
Предупреждаю, все ниже написанное является реальным опытом, а не когнитивной эквилибристикой. И так, погнали.
HTTP
Первым делом нужно очень четко разделить слои. Слой транспорта — 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-приложения должна начинаться с проектирования транспортного слоя. Надеюсь, сомнений в этом не осталось.
REST
Задам риторический вопрос — что это такое? И что вы ответили себе на него? Не буду давать ссылки на очевидные пруфы, но скорее всего не совсем то, чем он является по сути Это лишь идеология, стиль. Некие соображения на тему — как лучше общаться с бэком. И не просто общаться, а общаться в 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 это нормально. И более того — правильно.
Давайте еще раз вернемся к вопросу — почему это правильно? Потому что:
- Код 500 это инфраструктурный маркер, на основании которого нода на которой возникает проблема может быть отключена;
- Коды 5xx это то, что мониторится и если такой код возникает, любая система мониторинга тут же вас известит об этом. И служба поддержки вовремя сможет подключиться к решению проблемы;
- Вы не пишите дополнительный код. Не тратите на это драгоценное время. Не усложняете архитектуру. Вы не занимаетесь несвойственными вам проблемами — вы пишите прикладной код. То, что от вас хотят. За что платят.
- Трейс который выпадет по ошибке 500 будет куда как полезнее, чем ваши попытки его превзойти.
- Если REST запрос вернет 500 код, фронт уже на моменте обработки ответа будет знать, по какому алгоритму его обрабатывать. Причем, суть дела никак не изменится, вы как ничего толкового не получили и с 200, так и с 500. Но с 500 вы получили профит — осознание того, что это НЕОЖИДАННАЯ ошибка.
- Код 500 придет гарантированно. Независимо от того насколько плохо или хорошо вы написали свой код. Это ваша точка опоры.
Отдельно забью гвоздь во все “тело” кода 200:
7. Даже если вы очень сильно постараетесь избежать иных кодов ответа от сервера кроме как 200 на ваши запросы, вы не сможете это сделать. Вам может ответить на ваш запрос любой сервер посредник, совершенно любым кодом. И вы ДОЛЖНЫ будете такой ответ обработать корректно.
Итого, на логическом уровне борьба за код 200 бессмысленна.
Теперь давайте вернемся к инфраструктурному уровню. Очень часто слышу мнение — код 5xx не прикладного уровня, его нельзя отдавать бэком. Кхм, ну… тут есть противоречие в самом утверждении. Отдавать можно. Но код этот не прикладного уровня. Вот так вернее. Для понимания этого, предлагаю рассмотреть кейс:
Вы реализуете шлюз. У вас несколько ДЦ, на каждом свой канал связи к некоему приватному сервису. Ну, к примеру, к платежке по VPN. И есть канал коммуникации с Интернет. Вы получаете запрос на операцию со шлюзом, но… сервис оказывается недоступен.
И так, что вы должны ответить? Кому? Это проблема именно инфраструктурная и, именно, бэк столкнулся с ней. Конечно, нужно смело отвечать 503. Эти действия приведут к тому, что нода будет отключена балансировщиком на какое-то время. При этом, балансировщик при правильной настройке, не разрывая соединение с клиентом, отправит запрос в другую ноду. И… конечный клиент, с великой долей вероятности получил 200. А не кастомное описание ошибки, которая ему ничем не поможет.
Где и какой код использовать
Вопрос непростой. На него нет однозначного ответа. Для каждой системы проектируется транспортный слой и коды в нем могут быть специфичные.
Есть принятые стандарты. Их можно легко найти и, опять же, не буду очевидные пруфы приводить. Но, приведу неочевидный — developer.mozilla.org/ru/docs/Web/HTTP/Status
Почему его? Все дело в том, что обработчики кода могут вести себя по разному, в зависимости от реализации и контекста “понимания кода”. К примеру, в браузерах есть стратегия кеширования, завязанная на коды ответа. А в некоторых сервисах есть свои, кастомные коды. Например, CloudFlare.
Т.е. принятие решений об использовании кодов, нужно базировать на всех элементах входящих в транспортный слой от вашего кода на бэке до кода на клиенте. Только так можно найти верные ответы. Я даже пытаться тут дать всем универсальную пилюлю не буду.
Корни зла
Уже третий проект, в который я прихожу страдает кодом 200 в REST. Именно страдает. Другого слова нет. Если вы внимательно прочли всё до текущего момента, вы уже понимаете, что как только проект начинает расти, у него появляется потребность в развитии инфраструктуры, в ее устойчивости. Код 200 убивает все эти потуги на корню. И первое, что приходится делать — ломать стереотипы.
Корень зла, мне кажется лежит в том, что код 500, это первое, что web-разработчик встречает в своей профессиональной деятельности. Это, можно сказать, детская травма. И все его старания поначалу сводятся к тому, чтобы получить код 200.
Кстати, по какой-то причине, на этом же этапе развивается устойчивое мнение, что только ответы с кодом 200 могут быть снабжены телом. Конечно, это не так и с любым кодом может “приехать” любой ответ. Код это код. Тело это тело.
Далее, с развитием разработчика, у него возникают потребности в управлении багами собственного приложения. Но…, он не умеет пользоваться логами. Не умеет настраивать web-сервер. Он учится. И рождаются те самые «велики». Потому что, они ему доступны и он может их быстро сделать. Далее, на этот «велик» он монтирует новые колеса, усиливает раму и т.д. И этот велик становится его спутником на достаточно длительный промежуток времени, пока… пока у него не появляются реально сложные, многокомпонентные задачи. И тут, как говорится — вход в супермаркет с «великами» и на роликах запрещен.
P.S.: Автор упомянутой статьи восстановил ее из черновиков — habr.com/ru/post/440382, поэтому можно ознакомиться с ней тоже.
P.P.S.: Я постарался изложить все грани необходимости использования релевантных кодов ответа в REST. Я не буду отвечать на комментарии, прошу понять меня правильно. С большим вниманием буду их читать, но добавить мне нечего. Огромное спасибо за то, что вам хватило терпения прочесть статью!
REST APIs use the Status-Line part of an HTTP response message to inform clients of their request’s overarching result. RFC 2616 defines the Status-Line syntax as shown below:
Status-Line = HTTP-Version SP Status-Code SP Reason-Phrase CRLF
HTTP defines these standard status codes that can be used to convey the results of a client’s request. The status codes are divided into five categories.
- 1xx: Informational – Communicates transfer protocol-level information.
- 2xx: Success – Indicates that the client’s request was accepted successfully.
- 3xx: Redirection – Indicates that the client must take some additional action in order to complete their request.
- 4xx: Client Error – This category of error status codes points the finger at clients.
- 5xx: Server Error – The server takes responsibility for these error status codes.
1xx Status Codes [Informational]
|
Status Code |
Description |
|---|---|
|
100 Continue |
An interim response. Indicates to the client that the initial part of the request has been received and has not yet been rejected by the server. The client SHOULD continue by sending the remainder of the request or, if the request has already been completed, ignore this response. The server MUST send a final response after the request has been completed. |
|
101 Switching Protocol |
Sent in response to an Upgrade request header from the client, and indicates the protocol the server is switching to. |
|
102 Processing (WebDAV) |
Indicates that the server has received and is processing the request, but no response is available yet. |
|
103 Early Hints |
Primarily intended to be used with the |
2xx Status Codes [Success]
|
Status Code |
Description |
|---|---|
|
200 OK |
Indicates that the request has succeeded. |
|
201 Created |
Indicates that the request has succeeded and a new resource has been created as a result. |
|
202 Accepted |
Indicates that the request has been received but not completed yet. It is typically used in log running requests and batch processing. |
|
203 Non-Authoritative Information |
Indicates that the returned metainformation in the entity-header is not the definitive set as available from the origin server, but is gathered from a local or a third-party copy. The set presented MAY be a subset or superset of the original version. |
|
204 No Content |
The server has fulfilled the request but does not need to return a response body. The server may return the updated meta information. |
|
205 Reset Content |
Indicates the client to reset the document which sent this request. |
|
206 Partial Content |
It is used when the |
|
207 Multi-Status (WebDAV) |
An indicator to a client that multiple operations happened, and that the status for each operation can be found in the body of the response. |
|
208 Already Reported (WebDAV) |
Allows a client to tell the server that the same resource (with the same binding) was mentioned earlier. It never appears as a true HTTP response code in the status line, and only appears in bodies. |
|
226 IM Used |
The server has fulfilled a GET request for the resource, and the response is a representation of the result of one or more instance-manipulations applied to the current instance. |
3xx Status Codes [Redirection]
|
Status Code |
Description |
|---|---|
|
300 Multiple Choices |
The request has more than one possible response. The user-agent or user should choose one of them. |
|
301 Moved Permanently |
The URL of the requested resource has been changed permanently. The new URL is given by the |
|
302 Found |
The URL of the requested resource has been changed temporarily. The new URL is given by the |
|
303 See Other |
The response can be found under a different URI and SHOULD be retrieved using a GET method on that resource. |
|
304 Not Modified |
Indicates the client that the response has not been modified, so the client can continue to use the same cached version of the response. |
|
305 Use Proxy (Deprecated) |
Indicates that a requested response must be accessed by a proxy. |
|
306 (Unused) |
It is a reserved status code and is not used anymore. |
|
307 Temporary Redirect |
Indicates the client to get the requested resource at another URI with same method that was used in the prior request. It is similar to |
|
308 Permanent Redirect (experimental) |
Indicates that the resource is now permanently located at another URI, specified by the |
4xx Status Codes (Client Error)
|
Status Code |
Description |
|---|---|
|
400 Bad Request |
The request could not be understood by the server due to incorrect syntax. The client SHOULD NOT repeat the request without modifications. |
|
401 Unauthorized |
Indicates that the request requires user authentication information. The client MAY repeat the request with a suitable Authorization header field |
|
402 Payment Required (Experimental) |
Reserved for future use. It is aimed for using in the digital payment systems. |
|
403 Forbidden |
Unauthorized request. The client does not have access rights to the content. Unlike 401, the client’s identity is known to the server. |
|
404 Not Found |
The server can not find the requested resource. |
|
405 Method Not Allowed |
The request HTTP method is known by the server but has been disabled and cannot be used for that resource. |
|
406 Not Acceptable |
The server doesn’t find any content that conforms to the criteria given by the user agent in the |
|
407 Proxy Authentication Required |
Indicates that the client must first authenticate itself with the proxy. |
|
408 Request Timeout |
Indicates that the server did not receive a complete request from the client within the server’s allotted timeout period. |
|
409 Conflict |
The request could not be completed due to a conflict with the current state of the resource. |
|
410 Gone |
The requested resource is no longer available at the server. |
|
411 Length Required |
The server refuses to accept the request without a defined Content- Length. The client MAY repeat the request if it adds a valid |
|
412 Precondition Failed |
The client has indicated preconditions in its headers which the server does not meet. |
|
413 Request Entity Too Large |
Request entity is larger than limits defined by server. |
|
414 Request-URI Too Long |
The URI requested by the client is longer than the server can interpret. |
|
415 Unsupported Media Type |
The media-type in |
|
416 Requested Range Not Satisfiable |
The range specified by the |
|
417 Expectation Failed |
The expectation indicated by the |
|
418 I’m a teapot (RFC 2324) |
It was defined as April’s lool joke and is not expected to be implemented by actual HTTP servers. (RFC 2324) |
|
420 Enhance Your Calm (Twitter) |
Returned by the Twitter Search and Trends API when the client is being rate limited. |
|
422 Unprocessable Entity (WebDAV) |
The server understands the content type and syntax of the request entity, but still server is unable to process the request for some reason. |
|
423 Locked (WebDAV) |
The resource that is being accessed is locked. |
|
424 Failed Dependency (WebDAV) |
The request failed due to failure of a previous request. |
|
425 Too Early (WebDAV) |
Indicates that the server is unwilling to risk processing a request that might be replayed. |
|
426 Upgrade Required |
The server refuses to perform the request. The server will process the request after the client upgrades to a different protocol. |
|
428 Precondition Required |
The origin server requires the request to be conditional. |
|
429 Too Many Requests |
The user has sent too many requests in a given amount of time (“rate limiting”). |
|
431 Request Header Fields Too Large |
The server is unwilling to process the request because its header fields are too large. |
|
444 No Response (Nginx) |
The Nginx server returns no information to the client and closes the connection. |
|
449 Retry With (Microsoft) |
The request should be retried after performing the appropriate action. |
|
450 Blocked by Windows Parental Controls (Microsoft) |
Windows Parental Controls are turned on and are blocking access to the given webpage. |
|
451 Unavailable For Legal Reasons |
The user-agent requested a resource that cannot legally be provided. |
|
499 Client Closed Request (Nginx) |
The connection is closed by the client while HTTP server is processing its request, making the server unable to send the HTTP header back. |
5xx Status Codes (Server Error)
|
Status Code |
Description |
|---|---|
|
500 Internal Server Error |
The server encountered an unexpected condition that prevented it from fulfilling the request. |
|
501 Not Implemented |
The HTTP method is not supported by the server and cannot be handled. |
|
502 Bad Gateway |
The server got an invalid response while working as a gateway to get the response needed to handle the request. |
|
503 Service Unavailable |
The server is not ready to handle the request. |
|
504 Gateway Timeout |
The server is acting as a gateway and cannot get a response in time for a request. |
|
505 HTTP Version Not Supported (Experimental) |
The HTTP version used in the request is not supported by the server. |
|
506 Variant Also Negotiates (Experimental) |
Indicates that the server has an internal configuration error: the chosen variant resource is configured to engage in transparent content negotiation itself, and is therefore not a proper endpoint in the negotiation process. |
|
507 Insufficient Storage (WebDAV) |
The method could not be performed on the resource because the server is unable to store the representation needed to successfully complete the request. |
|
508 Loop Detected (WebDAV) |
The server detected an infinite loop while processing the request. |
|
510 Not Extended |
Further extensions to the request are required for the server to fulfill it. |
|
511 Network Authentication Required |
Indicates that the client needs to authenticate to gain network access. |
6. REST Specific HTTP Status Codes
200 (OK)
It indicates that the REST API successfully carried out whatever action the client requested and that no more specific code in the 2xx series is appropriate.
Unlike the 204 status code, a 200 response should include a response body. The information returned with the response is dependent on the method used in the request, for example:
- GET an entity corresponding to the requested resource is sent in the response;
- HEAD the entity-header fields corresponding to the requested resource are sent in the response without any message-body;
- POST an entity describing or containing the result of the action;
- TRACE an entity containing the request message as received by the end server.
201 (Created)
A REST API responds with the 201 status code whenever a resource is created inside a collection. There may also be times when a new resource is created as a result of some controller action, in which case 201 would also be an appropriate response.
The newly created resource can be referenced by the URI(s) returned in the entity of the response, with the most specific URI for the resource given by a Location header field.
The origin server MUST create the resource before returning the 201 status code. If the action cannot be carried out immediately, the server SHOULD respond with a 202 (Accepted) response instead.
202 (Accepted)
A 202 response is typically used for actions that take a long while to process. It indicates that the request has been accepted for processing, but the processing has not been completed. The request might or might not be eventually acted upon, or even maybe disallowed when processing occurs.
Its purpose is to allow a server to accept a request for some other process (perhaps a batch-oriented process that is only run once per day) without requiring that the user agent’s connection to the server persist until the process is completed.
The entity returned with this response SHOULD include an indication of the request’s current status and either a pointer to a status monitor (job queue location) or some estimate of when the user can expect the request to be fulfilled.
204 (No Content)
The 204 status code is usually sent out in response to a PUT, POST, or DELETE request when the REST API declines to send back any status message or representation in the response message’s body.
An API may also send 204 in conjunction with a GET request to indicate that the requested resource exists, but has no state representation to include in the body.
If the client is a user agent, it SHOULD NOT change its document view from that which caused the request to be sent. This response is primarily intended to allow input for actions to take place without causing a change to the user agent’s active document view. However, any new or updated metainformation SHOULD be applied to the document currently in the user agent’s dynamic view.
The 204 response MUST NOT include a message-body and thus is always terminated by the first empty line after the header fields.
301 (Moved Permanently)
The 301 status code indicates that the REST API’s resource model has been significantly redesigned, and a new permanent URI has been assigned to the client’s requested resource. The REST API should specify the new URI in the response’s Location header, and all future requests should be directed to the given URI.
You will hardly use this response code in your API as you can always use the API versioning for the new API while retaining the old one.
302 (Found)
The HTTP response status code 302 Found is a common way of performing URL redirection. An HTTP response with this status code will additionally provide a URL in the Location header field. The user agent (e.g., a web browser) is invited by a response with this code to make a second. Otherwise identical, request to the new URL specified in the location field.
Many web browsers implemented this code in a manner that violated this standard, changing the request type of the new request to GET, regardless of the type employed in the original request (e.g., POST). RFC 1945 and RFC 2068 specify that the client is not allowed to change the method on the redirected request. The status codes 303 and 307 have been added for servers that wish to make unambiguously clear which kind of reaction is expected of the client.
303 (See Other)
A 303 response indicates that a controller resource has finished its work, but instead of sending a potentially unwanted response body, it sends the client the URI of a response resource. The response can be the URI of the temporary status message, or the URI to some already existing, more permanent, resource.
Generally speaking, the 303 status code allows a REST API to send a reference to a resource without forcing the client to download its state. Instead, the client may send a GET request to the value of the Location header.
The 303 response MUST NOT be cached, but the response to the second (redirected) request might be cacheable.
304 (Not Modified)
This status code is similar to 204 (“No Content”) in that the response body must be empty. The critical distinction is that 204 is used when there is nothing to send in the body, whereas 304 is used when the resource has not been modified since the version specified by the request headers If-Modified-Since or If-None-Match.
In such a case, there is no need to retransmit the resource since the client still has a previously-downloaded copy.
Using this saves bandwidth and reprocessing on both the server and client, as only the header data must be sent and received in comparison to the entirety of the page being re-processed by the server, then sent again using more bandwidth of the server and client.
307 (Temporary Redirect)
A 307 response indicates that the REST API is not going to process the client’s request. Instead, the client should resubmit the request to the URI specified by the response message’s Location header. However, future requests should still use the original URI.
A REST API can use this status code to assign a temporary URI to the client’s requested resource. For example, a 307 response can be used to shift a client request over to another host.
The temporary URI SHOULD be given by the Location field in the response. Unless the request method was HEAD, the entity of the response SHOULD contain a short hypertext note with a hyperlink to the new URI(s). If the 307 status code is received in response to a request other than GET or HEAD, the user agent MUST NOT automatically redirect the request unless it can be confirmed by the user, since this might change the conditions under which the request was issued.
400 (Bad Request)
400 is the generic client-side error status, used when no other 4xx error code is appropriate. Errors can be like malformed request syntax, invalid request message parameters, or deceptive request routing etc.
The client SHOULD NOT repeat the request without modifications.
401 (Unauthorized)
A 401 error response indicates that the client tried to operate on a protected resource without providing the proper authorization. It may have provided the wrong credentials or none at all. The response must include a WWW-Authenticate header field containing a challenge applicable to the requested resource.
The client MAY repeat the request with a suitable Authorization header field. If the request already included Authorization credentials, then the 401 response indicates that authorization has been refused for those credentials. If the 401 response contains the same challenge as the prior response, and the user agent has already attempted authentication at least once, then the user SHOULD be presented the entity that was given in the response, since that entity might include relevant diagnostic information.
403 (Forbidden)
A 403 error response indicates that the client’s request is formed correctly, but the REST API refuses to honor it, i.e., the user does not have the necessary permissions for the resource. A 403 response is not a case of insufficient client credentials; that would be 401 (“Unauthorized”).
Authentication will not help, and the request SHOULD NOT be repeated. Unlike a 401 Unauthorized response, authenticating will make no difference.
404 (Not Found)
The 404 error status code indicates that the REST API can’t map the client’s URI to a resource but may be available in the future. Subsequent requests by the client are permissible.
No indication is given of whether the condition is temporary or permanent. The 410 (Gone) status code SHOULD be used if the server knows, through some internally configurable mechanism, that an old resource is permanently unavailable and has no forwarding address. This status code is commonly used when the server does not wish to reveal exactly why the request has been refused, or when no other response is applicable.
405 (Method Not Allowed)
The API responds with a 405 error to indicate that the client tried to use an HTTP method that the resource does not allow. For instance, a read-only resource could support only GET and HEAD, while a controller resource might allow GET and POST, but not PUT or DELETE.
A 405 response must include the Allow header, which lists the HTTP methods that the resource supports. For example:
Allow: GET, POST
406 (Not Acceptable)
The 406 error response indicates that the API is not able to generate any of the client’s preferred media types, as indicated by the Accept request header. For example, a client request for data formatted as application/xml will receive a 406 response if the API is only willing to format data as application/json.
If the response could be unacceptable, a user agent SHOULD temporarily stop receipt of more data and query the user for a decision on further actions.
412 (Precondition Failed)
The 412 error response indicates that the client specified one or more preconditions in its request headers, effectively telling the REST API to carry out its request only if certain conditions were met. A 412 response indicates that those conditions were not met, so instead of carrying out the request, the API sends this status code.
415 (Unsupported Media Type)
The 415 error response indicates that the API is not able to process the client’s supplied media type, as indicated by the Content-Type request header. For example, a client request including data formatted as application/xml will receive a 415 response if the API is only willing to process data formatted as application/json.
For example, the client uploads an image as image/svg+xml, but the server requires that images use a different format.
500 (Internal Server Error)
500 is the generic REST API error response. Most web frameworks automatically respond with this response status code whenever they execute some request handler code that raises an exception.
A 500 error is never the client’s fault, and therefore, it is reasonable for the client to retry the same request that triggered this response and hope to get a different response.
The API response is the generic error message, given when an unexpected condition was encountered and no more specific message is suitable.
501 (Not Implemented)
The server either does not recognize the request method, or it cannot fulfill the request. Usually, this implies future availability (e.g., a new feature of a web-service API).
References :
https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml
Error handling is one of the key components of REST API best practices.
Hope for the best, prepare for the worst.
In this article, we’ll explore everything you need to know about handling errors in REST APIs.
Best practices of error handling in REST APIs consist of:
1. HTTP Status Codes
HTTP status codes are the most important indicator of errors in REST APIs.
Out of five categories of HTTP status codes, two are used for errors:
- 400 range: Client Errors — where something is wrong on the user’s end
- 500 range: Protocol Errors — indicating issues from within in terms of fault processing.
Most common HTTP error status codes
Here is a table of the most common HTTP error codes and their explanations:
| HTTP Status Code | Explanation |
|---|---|
| 400 Bad Request |
The request was malformed or invalid, and the server could not process |
| 401 Unauthorized |
The request requires authentication, and the client did not provide |
| 403 Forbidden |
The client does not have permission to access the requested resource. |
| 404 Not Found | The requested resource could not be found on the server. |
| 405 Method Not Allowed | The requested method is not supported by the resource. |
| 429 Too Many Requests |
The client has made too many requests in a specified time period and is |
| 500 Internal Server Error |
An unexpected error occurred on the server, and it was unable to process |
| 503 Service Unavailable |
The server is temporarily unable to handle the request due to |
Read more: HTTP Bad Request vs Not Found
HTTP error status codes tell us that the request failed, but they don’t provide domain-specific details. That’s why we add error codes to the response body.
2. REST API Error Codes
REST API error codes are domain-specific error identifiers that proved more detailed information about the error.
Error codes are communicated to the client in the response body along with a relevant error message.
3. REST API Error message
It’s important to include the error message in the response body because it helps our API consumers understand the error context.
The error message is usually a one sentence that should tell more than what we know from the status code.
For example, returning the status code 401 Unauthorized with the error message Unauthorized request doesn’t provide much information on why the request was unauthorized. A better error message could be This feature is not in your access scope.
The response body of an errored request should not contain the error stack trace.
4. Error Trace ID
An error trace ID is a unique identifier that is generated when an error occurs.
It can be used to track and trace the error throughout the system. The unique ID makes it easier for API developers to identify, diagnose, and resolve issues.
The error trace ID is typically included in the response body of an error response. It can also be logged by the API and other systems along the request-response path, providing a complete and detailed trace of the error.
Having a unique error trace ID is particularly useful in microservice architectures, where multiple services may be involved in processing a single request. The error trace ID can be used to correlate errors across multiple services and to trace the request-response path through the system.
5. Error Message Formatting
If you’re using JSON, using the application/problem+json (Problem Detail) media type is the best way to format the error response.
Using the «problem detail» response body just means putting together all the best practices we’ve talked about.
The problem detail body must include the error:
- Type or status code — unique error identifier
- Title
- Detail — Brief error explanation.
Internet Engineering Task Force (IETF) defines a «problem detail» approach in RFC7807.
Negative Testing REST API
Negative Testing is a REST API feature that lets API clients simulate errors.
The sandbox API defines request bodies you can use to guarantee a certain error response.
Negative Testing is crucial for developing a robust integration because it’s impossible to organically test out all the error states.
HTTP Error Statuses vs Error Codes
The main difference between HTTP error status codes and error codes is that HTTP error status codes are standardized and widely recognized across the web, while error codes are specific to a particular application or service.
HTTP error status codes are three-digit codes that indicate the outcome of a request, such as success (200 OK), client error (4xx) or server error (5xx). They provide a basic level of error information and are widely understood by API clients.
Error codes, on the other hand, are custom codes that provide more detailed information about an error. They can be used to provide additional context about the error, such as indicating the specific validation error or the type of resource that caused the error. Error codes can be communicated to the client in the response body along with a relevant error message.
REST API Error Handling Best Practices Summary
Best Practices:
- HTTP Status Codes: Use HTTP status codes to indicate errors in REST APIs.
- Error Codes: Use domain-specific error codes to provide more detailed information about the error.
- Error Messages: Include error messages in the response body to help API consumers understand the error context.
- Error Trace ID: Use a unique error trace ID to track and trace errors throughout the system.
- Error Message Format: Use the application/problem+json (Problem Detail) media type to format error responses in JSON.
FAQ: REST API Error Handling
Should the response body include the HTTP status code?
The response body should not include the HTTP status code.
Including it in the response body adds to the network payload and it is redundant.
Why is it important to use proper HTTP error status codes?
It’s important to use proper HTTP error statuses because they are standardized across the web.
They are widely recognized and understood by API clients, tools, and services.
For example, Application Performance Monitoring tools (APM) automatically categorize errors based on their HTTP status codes and provide valuable insights into the performance and health of the API. If an error happens and we return the «200 OK» status, an APM wouldn’t catch it.
Similarly, API gateways and load balancers can be configured to route requests based on the HTTP status code, allowing for fine-grained control over the API behavior.
Should error response include the exception message?
Based on RFC7807, error response should not include the exception message or stack trace:
Problem details are not a debugging tool for the underlying implementation; rather, they are a way to expose greater detail about the HTTP interface itself. — RFC7807
Published on:
Коды состояний HTTP
Данная страница основана на информации о кодах состояний HTTP. Оригинальными источниками являются ietf.org и Wikipedia. Кликните по заголовку категории или коду состояния для получения подробной
информации.
1xx:
Information
В этот класс выделены коды, информирующие о процессе передачи.
Это обычно предварительный ответ, состоящий только из Status-Line и опциональных заголовков,
и завершается пустой строкой. Нет обязательных заголовков для этого класса кодов состояния.
Из-за того, что стандарт протокола HTTP/1.0 не определял никаких 1xx кодов состояния,
серверы НЕ ДОЛЖНЫ посылать 1xx ответы HTTP/1.0 клиентам, за исключением экспериментальных условий.
Клиент должен быть готов принять один или несколько 1xx ответов статуса до завершения передачи,
даже если клиент не ожидает статуса 100 (Продолжить). Неожиданные 1xx ответы могут быть проигнорированы
агентом пользователя.
Прокси должен направить 1xx ответы, если соединение между прокси-сервером и клиентом было закрыто,
или если прокси-сервер сам просил 1xx ответ. (Например, если прокси-сервер добавляет «Expect: 100-continue»
поле, когда он перенаправляет запрос, то нужно отправить соответствующий 100 (Continue) код ответа).
Wikipedia
В этот класс выделены коды, информирующие о процессе передачи.
При работе через протокол HTTP версии 1.0 сообщения с такими кодами должны игнорироваться.
В версии 1.1 клиент должен быть готов принять этот класс сообщений как обычный ответ,
но серверу отправлять что-либо не нужно.
Сами сообщения от сервера содержат только стартовую строку ответа и, если требуется,
несколько специфичных для ответа полей заголовка.
Прокси-сервера подобные сообщения должны отправлять дальше от сервера к клиенту.
100: Continue
Клиент должен продолжать свой Запрос. Этот промежуточный ответ используется для сообщения клиенту о том,
что начальная часть запроса была получена и ещё не была отвергнута сервером.
Клиенту СЛЕДУЕТ продолжить посылку оставшихся данных запроса или,
если запрос уже был выполнен, игнорировать этот ответ.
Сервер ДОЛЖЕН послать заключительный ответ после того, как запрос был завершен.
См. раздел 8.2.3 для детального обсуждения использования и обработки этого кода состояния.
Wikipedia
Сервер удовлетворён начальными сведениями о запросе, клиент может продолжать пересылать заголовки. Появился
в HTTP/1.1.
101: Switching
Protocols
Сервер понимает и готов выполнить запрос клиента через поле заголовка сообщения Upgrade (раздел 14.42)
об изменении протокола приложения, используемого в этом соединении.
Сервер переключит протоколы на те, которые определены в поле заголовка Upgrade ответа сразу после пустой
строки, завершающей ответ 101.
Протокол СЛЕДУЕТ переключать только тогда, когда это выгодно.
Например, переключение на более новую версию HTTP выгодно по сравнению со старыми версиями,
а переключение на синхронный протокол реального времени может быть выгодным при доставке ресурсов,
которые используют такие функции.
Wikipedia
Сервер предлагает перейти на более подходящий для указанного ресурса протокол;
список предлагаемых протоколов сервер обязательно указывает в поле заголовка Upgrade.
Если клиента это заинтересует, то он посылает новый запрос с указанием другого протокола. Появился в
HTTP/1.1.
102: Processing (WebDAV)
Этот промежуточный ответ используется для информирования клиента о том, что сервер принял на себя полный
запрос, но ещё не завершил его.
Этот статус код должен быть послан только когда сервер имеет разумные основания ожидать, что запрос займёт
значительное время.
В качестве ориентира, если метод занимает больше времени, чем на 20 секунд (разумное, но произвольное
значение)
для обработки сервер должен вернуть 102 (Processing) ответ. Сервер ДОЛЖЕН послать заключительный ответ после
того, как запрос был завершен.
Методы потенциально могут занять длительный период времени для процесса,
особенно если они поддерживают заголовок Depth.
В таких случаях клиент может прервать соединение по тайм-ауту во время ожидания ответа.
Чтобы предотвратить это, сервер может вернуть 102 (Processing) код состояния, указывая клиенту,
что сервер всё ещё обрабатывается методом.
Wikipedia
Запрос принят, но на его обработку понадобится длительное время.
Используется сервером, чтобы клиент не разорвал соединение из-за превышения времени ожидания.
Клиент при получении такого ответа должен сбросить таймер и дожидаться следующей команды в обычном режиме.
Появился в WebDAV.
2xx:
Success
Этот класс кодов состояния указывает, что запрос клиента был успешно получен, понят и принят.
Wikipedia
Этот класс кодов состояния указывает, что действие, запрошенное клиентом, было получено, понято и принято.
* 200: OK
Запрос выполнен успешно. Информация, возвращаемая с ответом зависит от метода, используемого в запросе,
например:
- GET Получить объект, соответствующий запрошенному ресурсу в ответ;
- HEAD Поля заголовков, соответствующие запрошенному ресурсу отправляются в ответ без какого-либо тела
сообщения; - POST Созданный объект или иной результат действия;
- TRACE Объект, содержащий сообщение запроса, полученное сервером.
Wikipedia
Стандартный ответ для запросов по HTTP.
Основной код ответа. Обычно используется для того, чтобы показать успешность
выполненной операции.
* 201: Created
Запрос был выполнен, и в результате был создан новый ресурс.
На вновь созданный ресурс можно ссылаться с помощью URI, возвращаемого в сущности ответа,
с наиболее конкретным URI для ресурса, заданным полем заголовка Location.
В ответ СЛЕДУЕТ включать объект, содержащий список характеристик ресурса и местоположения,
из которых пользователь или пользовательский агент может выбрать наиболее подходящий.
Формат объекта определяется типом носителя, указанным в поле заголовка Content-Type.
Исходный сервер ДОЛЖЕН создать ресурс перед возвратом кода состояния 201.
Если действие не может быть выполнено немедленно, сервер ДОЛЖЕН ответить ответом 202 (Принято).
Ответ 201 МОЖЕТ содержать поле заголовка ответа ETag, указывающее текущее значение тега объекта
для только что созданного запрошенного варианта, см. Раздел 14.19.
Wikipedia
Запрос был выполнен и в результате был создан новый ресурс.
Подтверждение успешного создания (например посредством POST или PUT запроса).
Заголовок Location содержит ссылку на только что созданный ресурс (при POST запросе).
Тело ответа может быть пустым. Обычно так и бывает.
202: Accepted
Запрос принят в обработку, но ещё не завершен.
Нет никаких гарантий, что запрос успешно выполнится в процессе обработки данных.
Из-за асинхронного типа выполняемой операции отсутствует возможность повторной отправки статуса.
Данный ответ ничему не обязывает.
Основной целью этого запроса является уведомить клиента о том, что запрос принят в обработку
и, ввиду того, что наличие соединения между клиентом и сервером после этого не обязательно,
позволить серверу принять запрос от другого клиента/для другого процесса.
В ответе должно также возвращаться состояние выполнение запроса или ссылка на источник,
где пользователь может проверить статус выполнения задачи или убедиться в её завершении.
Wikipedia
Запрос был принят на обработку, но она не завершена.
Клиенту необязательно дожидаться окончательной передачи сообщения, так как может быть начат очень долгий
процесс.
Появился в HTTP/1.0.
203: Non-Authoritative
Information
Предоставленная информация взята не из оригинального источника (а, например,
из кэша, который мог устареть, или из резервной копии, которая могла потерять актуальность).
Этот факт отражен в заголовке ответа и подтверждается этим кодом.
Предоставленная информация может совпадать, а может и не совпадать с оригинальными данными.
Wikipedia
Аналогично ответу 200, но в этом случае передаваемая информация была взята не из первичного источника
(резервной копии, другого сервера и т. д.) и поэтому может быть неактуальной.
Появился в HTTP/1.1.
* 204: No Content
Запрос был успешно обработан, но нет необходимости возвращать какие-либо данные.
Так же в ответе может возвращаться новая, или обновлённая информация, однако в итоге она не будет отличаться
о того,
что было изначально послано на сервер и, таким образом, считается что клиент и так обладает актуальной
информацией.
Если клиентом является браузер — то он не должен изменять отображение документа,
и его состояние до момента отправки запроса и после этого — не должно изменяться.
Этот статус ответа в основном применяется для индикации успешности выполнения запроса с учётом того,
что данные и их представление не должны изменится, не смотря (или с учётом того), что новая (обновлённая
информация)
уже отображена в представлении документа.
Ответ 204 НЕ ДОЛЖЕН включать тело сообщения. Если таковое имеется — оно обычно игнорируется и считается что
после заголовков присутствует одна пустая линия.
Wikipedia
Сервер успешно обработал запрос, но в ответе были переданы только заголовки без тела сообщения.
Клиент не должен обновлять содержимое документа, но может применить к нему полученные метаданные. Появился в
HTTP/1.0.
Статус используется, когда ответ не используется или когда нет контента (например
при выполнении команды DELETE)
205: Reset Content
Сервер успешно обработал запрос и обязывает клиента сбросить введенные пользователем данные.
В ответе не должно передаваться никаких данных (в теле ответа).
Обычно применяется для возврата в начальное состояние формы ввода данных на клиенте.
Wikipedia
Сервер обязывает клиента сбросить введённые пользователем данные.
Тела сообщения сервер при этом не передаёт, и документ обновлять необязательно.
Появился в HTTP/1.1.
206: Partial
Content
Сервер выполнил часть GET запроса ресурса. Запрос ДОЛЖЕН был содержать поле заголовка
Range (секция 14.35), который указывает на желаемый диапазон и МОГ содержать
поле заголовка If-Range (секция 14.27), который делает запрос условным.
Запрос ДОЛЖЕН содержать следующие поля заголовка:
- Либо поле Content-Range (секция 14.16), который показывает диапазон, включённый
в этот запрос, либо Content-Type со значением multipart/byteranges, включающими в себя
поля Content-Range для каждой части. Если в заголовке запроса есть поле Content-Length,
его значение ДОЛЖНО совпадать с фактическим количеством октетов, переданных в теле сообщения. - Date
- ETag и/или Content-Location, если ранее был получен ответ 200 на такой же запрос.
- Expires, Cache-Control, и/или Vary, если значение поля изменилось с момента отправления
последнего такого же запроса
Если ответ 206 — это результат выполнения условного запроса, который использовал строгий
кэш-валидатор (подробнее в секции 13.3.3), в ответ НЕ СЛЕДУЕТ включать какие-либо другие
заголовки сущности. Если такой ответ — результат выполнения запроса If-Range, который
использовал «слабый» валидатор, то ответ НЕ ДОЛЖЕН содержать другие заголовки сущности;
это предотвращает несоответствие между закэшированными телами сущностей и обновлёнными заголовками.
В противном случае ответ ДОЛЖЕН содержать все заголовки сущностей, которые вернули статус 200 (OK)
на тот же запрос.
Кэш НЕ ДОЛЖЕН объединять ответ 206 с другими ранее закэшированными данными, если поле ETag или
Last-Modified в точности не совпадают (подробнее в секции 16.5.4)
Кэш, который не поддерживает заголовки Range и Content-Range НЕ ДОЛЖЕН кэшировать ответы
206 (Partial).
Wikipedia
Сервер передает только ту часть ресурса, которая была указана клиентом в заголовке диапазона.
Заголовок диапазона используется такими инструментами, как wget, для возобновления прерванных загрузок
или для разделения загрузки на несколько параллельных потоков.
207: Multi-Status
(WebDAV)
Код 207 (Multi-Status) позволяет передавать статусы для нескольких независимых операций (за подробностями в
секцию 11).
Wikipedia
Сервер передаёт результаты выполнения сразу нескольких независимых операций.
Они помещаются в само тело сообщения в виде XML-документа с объектом multistatus.
Не рекомендуется размещать в этом объекте статусы из серии 1xx из-за бессмысленности и избыточности.
Появился в WebDAV.
208: Already
Reported (WebDAV)
Относится к DAV и был ранее включён в 207 ответ. Там поныне и остаётся.
Wikipedia
На сайте описание отсутствует
226: IM Used
Сервер успешно принял запрос для ресурса и ответ является представлением результата применения
одной или нескольких манипуляций с экземпляром ресурса.
На самом деле актуальное представление ресурса может быть в текущий момент не доступно ввиду того,
что действие может быть глобальное и затрагивать несколько экземпляров ресурса, а соответственно может
комбинироваться с
предыдущим или возможным в будущем ответом, связанным со специфичными действиями над конкретным экземпляром
ресурса (или ресурсов).
Если это так, то при формировании заголовков для конкретного экземпляра (или в результирующих заголовках,
отталкивающихся от 226 ответа и других экземпляров) нужно руководствоваться частью 13.5.3 спецификации
HTTP/1.1.
Запрос обязан содержать в A-IM заголовке перечень как минимум одной манипуляции с экземпляром.
Ответ обязан содержать ETag заголовок с тегом для конкретного экземпляра.
Ответ переданный с 226 кодом может быть закэширован и использован в ответах, актуальность которых
регулируется
Cache-Control заголовком, а также требованиями, которые описаны в секции 10.6.
Ответ, переданный с кодом 226 может быть использован в совокупности с имеющимися закэшированными сущностями
для базового экземпляра
для создания кэшированной сущности для конкретного экземпляра.
Wikipedia
Заголовок A-IM от клиента был успешно принят и сервер возвращает содержимое с учётом указанных параметров.
Введено в RFC 3229 для дополнения протокола HTTP поддержкой дельта-кодирования.
3xx:
Redirect
Данный класс кодов состояния показывает, что дальнейшие действия должны быть выполнены клиентом для тоо,
чтобы запрос завершился успешно.
Требуемое действие может быть выполнено клиентом без участия пользователя тогда и только тогда, когда
следующий запрос будет GET или HEAD.
Клиент обязан обнаруживать бесконечные циклы перенаправлений, потому что они генерируют бессмысленный трафик.
Замечание: предыдущая версия спецификации допускала максимум 5 перенаправлений. Разработчики
должны иметь это ввиду.
Wikipedia
Коды этого класса сообщают клиенту, что для успешного выполнения операции необходимо сделать другой запрос,
как правило, по другому URI.
Из данного класса пять кодов 301, 302, 303, 305 и 307 относятся непосредственно к перенаправлениям.
Адрес, по которому клиенту следует произвести запрос, сервер указывает в заголовке Location.
При этом допускается использование фрагментов в целевом URI.
По последним стандартам клиент может производить перенаправление без запроса пользователя только, если второй
ресурс будет запрашиваться методом GET или HEAD.
В предыдущих спецификациях говорилось, что для избежания круговых переходов пользователя следует спрашивать
после 5-го подряд перенаправления.
При всех перенаправлениях, если метод запроса был не HEAD, то в тело ответа следует включить короткое
гипертекстовое сообщение с целевым адресом,
чтобы в случае ошибки пользователь смог сам произвести переход.
Разработчики HTTP отмечают, что многие клиенты при перенаправлениях с кодами 301 и 302 ошибочно применяют
метод GET ко второму ресурсу,
несмотря на то, что к первому запрос был с иным методом (чаще всего PUT).
Чтобы избежать недоразумений, в версии HTTP/1.1 были введены коды 303 и 307 и их рекомендовано использовать
вместо 302.
Изменять метод нужно только, если сервер ответил 303.
В остальных случаях следующий запрос производить с исходным методом.
300: Multiple
Choices
Запрошенный ресурс имеет множество представлений,
каждое из которых имеет своё расположение, и предоставляется управляемая агентом информация о переговорах
(раздел 12),
чтобы пользователь (или пользовательский агент) мог выбрать предпочтительное представление и перенаправить
его запрос в это место.
Если это не запрос HEAD, ответ ДОЛЖЕН включать объект, содержащий список характеристик и адресов,
из которого пользователь или агент пользователя может выбрать один наиболее подходящий.
Формат объекта определяется по типу данных приведённых в Content-Type поля заголовка.
В зависимости от формата и возможностей агента пользователя, выбор наиболее подходящего варианта может
выполняться автоматически.
Однако эта спецификация не определяет никакого стандарта для автоматического выбора.
Если у сервера есть предпочтительный выбор представления, он ДОЛЖЕН включить конкретный URI для этого
представления в поле Location;
агент пользователя МОЖЕТ использовать заголовок Location для автоматического перенаправления к предложенному
ресурсу.
Этот запрос может быть закэширован, если явно не было указано иного.
Wikipedia
По указанному URI существует несколько вариантов предоставления ресурса по типу MIME, по языку или по другим
характеристикам.
Сервер передаёт с сообщением список альтернатив, давая возможность сделать выбор клиенту автоматически или
пользователю.
Появился в HTTP/1.0.
301: Moved
Permanently
Запрашиваемому ресурсу был установлен новый URI и будущие обращения к этому ресурсу должны осуществляться по
возвращённому URI.
Клиенты с возможностью редактирования должны автоматически переопределить ссылки на Request-URI для одной
или более новых ссылок,
возвращённых сервером, где это возможно. Этот ответ является кэшируемым если не указано иное.
Новый постоянный URI должен быть передан в Location заголовке в ответе.
Если запрос был не HEAD — в ответе должно содержаться краткое описание того, что адрес изменился со ссылкой
на новый адрес.
Данная информация должна быть предоставлена в виде HTML.
Если 301 статус получен в ответ на запрос, отличный от GET или HEAD,
агент пользователя не обязан автоматически перенаправлять в случае, если пользователь не может подтвердить
это действие.
Замечание: Некоторые HTTP/1.0 клиенты, после автоматического перенаправления POST запроса,
после принятия 301 статуса, ошибочно преобразуют его в GET запрос.
Wikipedia
Запрошенный документ был окончательно перенесен на новый URI, указанный в поле Location заголовка.
Некоторые клиенты некорректно ведут себя при обработке данного кода.
Появился в HTTP/1.0.
302: Found
Запрошенный ресурс временно находится под другим URI.
Так как перенаправление может быть изменено в любой момент, клиенту СЛЕДУЕТ продолжать использовать тот же
самый URI для будущих запросов.
Этот ответ является кэшируемым если не было назначено Cache-Control или Expires поля заголовка.
Временный URI должен быть передан в Location заголовке в ответ на запрос.
В случае, если запрос был не HEAD — в ответе должно содержаться упоминание о новом URI в гипертекстовом
представлении.
Если 302 статус передан в ответе на отличный от GET или HEAD запрос, клиент не должен автоматически
выполнять перенаправление, если это действие не может быть подтверждено пользователем, так как это может
изменить условия, которые подразумевал исходный запрос.
Замечание: RFC 1945 и RFC 2068 описывают, что клиенту недопустимо изменять метод исходного
запроса при перенаправлении.
Тем не менее большинство существующих реализаций User Agent обрабатывает 302 как будто был передан ответ
303,
выполняя GET для адреса, переданного в Location, независимо от исходного метода запроса.
Статусы 303 и 307 были добавлены для серверов, которым необходимо однозначно понимать, какой вид реакции
ожидать от клиента.
Wikipedia
Запрошенный документ временно доступен по другому URI, указанному в заголовке в поле Location.
Этот код может быть использован, например, при управляемом сервером согласовании содержимого.
Некоторые клиенты некорректно ведут себя при обработке данного кода. Введено в HTTP/1.0.
303: See Other
Документ по запрошенному адресу может быть найден по другому URI и должен быть найден с использованием GET
запроса.
Этот метод существует прежде всего, чтобы позволить выход из POST-активированной сценария,
используя перенаправление агента пользователя на указанный ресурс.
Новый URI не является заменой для исходного адреса.
303 статус не должен быть закэширован, однако ресурс, куда будет выполнено перенаправления — может быть закэширован.
Новый URI должен быть передан посредством Location в ответе.
В случае, если исходный запрос был отличен от HEAD — в ответе должна содержаться ссылка на новый URI в
гипертекстовом формате.
Замечание: Многие агенты, до HTTP/1.1 не понимают статуса 303.
Когда взаимодействие с такими клиентами является проблемой,
код состояния 302 может быть использован вместо 303, так как большинство агентов реагируют на ответ 302,
так же как на 303.
Wikipedia
Документ по запрошенному URI нужно запросить по адресу в поле Location заголовка с использованием метода GET
несмотря даже на то,
что первый запрашивался иным методом. Этот код был введён вместе с 307-ым для избежания неоднозначности,
чтобы сервер был уверен, что следующий ресурс будет запрошен методом GET.
Например, на веб-странице есть поле ввода текста для быстрого перехода и поиска.
После ввода данных браузер делает запрос методом POST, включая в тело сообщения введённый текст.
Если обнаружен документ с введённым названием, то сервер отвечает кодом 303, указав в заголовке Location его
постоянный адрес.
Тогда браузер гарантировано его запросит методом GET для получения содержимого.
В противном случае сервер просто вернёт клиенту страницу с результатами поиска.
Введено в HTTP/1.1
* 304: Not Modified
Если клиент выполнил условный запрос GET и доступ разрешен, но документ не был изменен, сервер должен
ответить, используя этот код состояния.
Ответ 304 НЕ ДОЛЖЕН содержать тела сообщения, и, таким образом, всегда завершается первой пустой строкой
после полей заголовка.
Ответ должен содержать следующие заголовки:
- Дата, если её отсутствия не требует раздел 14.18.1
Если сервер подчиняется этим правилам, и прокси-серверы и клиенты добавят свои собственные Даты к любому
ответу,
полученному без Даты (как уже указано [RFC 2068], раздел 14.19), кэши будут работать правильно.
- ETag и/или Content-Location, если заголовки передаются с 200 кодом ответа.
- Expires, Cache-Control, и/или Vary, если значения полей изменились с последнего ответа на предыдущие
аналогичные запросы.
Если условный GET запрос использует строгую валидацию на присутствие в кэше (см 13.3.3) ответ НЕ должен
(желательно) включать другие заголовки.
В противном случае ответ НЕ должен (обязательно) включать другие заголовки.
Это предотвращает нарушение согласованности данных в кэше и модификации заголовков.
Если при 304 ответе наблюдается отсутствие сущности в актуальном кэше, запрос должен быть продолжен без
проверки присутствия кэша.
Если кэш использует полученный 304 ответ для обновления кэша, кэш ДОЛЖЕН обновить запись, чтобы отразить
любые новые значения полей, переданных в ответ.
Wikipedia
Сервер возвращает такой код, если
клиент запросил документ методом GET,
использовал заголовок If-Modified-Since или If-None-Match и
документ не изменился с указанного момента.
При этом сообщение сервера не должно содержать тела.
Появился в HTTP/1.0.
Используется для условных GET запросов для снижения нагрузки на сеть.
Если используется, то обязательны для передачи Data, Content-Location, ETag заголовки.
Тело ответа при этом статусе не передается.
305: использовать
прокси
Доступ к запрошенному ресурсу ДОЛЖЕН быть осуществлен через прокси-сервер, указанный в поле
Location. Поле Location предоставляет URI прокси. Ожидается, что получатель повторит этот
запрос с помощью прокси. Ответ 305 может генерироваться ТОЛЬКО серверами-источниками.
Заметьте: в спецификации RFC 2068 однозначно не сказано, что ответ 305 предназначен
для перенаправления единственного запроса, и что он должен генерироваться только
сервером-источником. Упущение этих ограничений вызвало ряд значительных последствий для
безопасности.
Wikipedia
Многие HTTP клиенты (такие, как Mozilla и Internet Explorer) обрабатывают этот
статус некорректно прежде всего из соображений безопасности.
306: зарезервировано (код
использовался только в ранних
спецификациях)
Статус 306 использовался в предыдущих версиях спецификации, но больше не используется
и код зарезервирован.
Wikipedia
Больше не используется. Раньше обозначал «последующие запросы должны использовать
указанный прокси-сервер»
307: Temporary
Redirect
Запрошенный ресурс временно находится по другому URI. Так как перенаправление может быть
изменено по какой-либо причине, клиенту следует продолжить использовать Request-URI
для последующих запросов. Этот ответ можно закэшировать только в том случае, если это
обозначено в заголовках Cache-Control или Expires.
Временный URI СЛЕДУЕТ передать в ответе в поле Location. Если метод запроса не HEAD,
в сущность запроса СЛЕДУЕТ включить короткую гипертекстовую заметку со ссылкой на новый
(новые) URI, поскольку многие агенты, использующие более ранние протоколы, чем HTTP/1.1,
не понимают статус 307. Поэтому заметка ДОЛЖНА содержать информацию, необходимую для
пользователя, чтобы повторить запрос на новый URI.
Если статус 307 получен в ответ на запрос, метод которого отличается от GET или HEAD, агент
НЕ ДОЛЖЕН автоматически перенаправлять запрос до тех пор, пока он не будет подтвержден
пользователем, поскольку это может изменить условия, из-за которых и был сгенерирован этот
запрос.
Wikipedia
В этом случае запрос следует повторить на другой URI; как бы то ни было, последующие
запросы могут использовать первоначальный URI. В противоположность статусу 302, метод запроса
не должен изменяться, когда первоначальный запрос пересоздается. Например, POST-запрос
нужно продублировать другим POST-запросом.
308: Permanent
Redirect (экспериментально)
Нужно повторить запрос на другой адрес без изменения применяемого метода.
Wikipedia
Этот и все последующие запросы нужно повторить на другой URI. 307 и 308, как было предложено,
схожи в поведении с 302 и 301, но не требуют замены HTTP метода. Таким образом, например,
отправку формы на «постоянно перенаправленный» ресурс можно продолжать без проблем.
4xx:
Client Error
Класс кодов 4xx предназначен для определения ошибок, которые произошли на стороне клиента.
Кроме случая, когда метод запроса был HEAD, серверу СЛЕДУЕТ включить в ответ сущность,
которая содержит в себе объяснение ситуации, которая привела к ошибке, и является ли это временным
или постоянным условием. Эти коды применимы к любому методу запроса. Пользовательским агентам
СЛЕДУЕТ отображать пользователю включённую в такой ответ сущность.
Если клиент передает данные, то серверу, использующему TCP СЛЕДУЕТ убедиться, что клиент
подтверждает отправку пакетов, содержащих ответ, до того, как сервер закроет соединение.
Если клиент продолжит отправку данных после того, как сервер закрыл соединение, TCP стек
сервера отправит пакет с флагом сброса (TCP reset packet), который может уничтожить клиентские
данные, находящиеся в неподтвержденных входных буферах, до того, как они будут прочитаны
и обработаны HTTP приложением.
Wikipedia
Класс кодов 4xx предназначен для указания ошибок со стороны клиента.
При использовании всех методов, кроме HEAD, сервер должен вернуть в теле сообщения гипертекстовое пояснение
для пользователя.
* 400: Bad Request
Запрос не удалось обработать из-за синтаксической ошибки. Клиенту НЕ СЛЕДУЕТ повторять такой
запрос без изменений.
Wikipedia
Сервер обнаружил в запросе клиента синтаксическую ошибку.
Появился в HTTP/1.0.
Общая ошибка во время выполнения запроса может вызвать неверное состояние. Примером,
вызывающим этот статус, может быть ошибка в валидации домена или нехватка данных.
* 401: Unauthorized
Запрос требует аутентификации пользователя.
Ответ должен содержать WWW-Authenticate заголовок (раздел 14.47).
Клиент может повторить запрос с корректным Authorization заголовком (раздел 14.8).
Если запрос уже содержит информацию для авторизации, в таком случае 401 код ответа показывает, что
авторизация была отклонена.
Если 401, содержит тот же самый вызов, как и предшествующий ответ, а агент пользователя уже делал попытку
аутентификации по крайней мере один раз,
то СЛЕДУЕТ показать пользователю объект, который был дан в ответе, так как этот объект может включать
соответствующую диагностическую информацию.
Аутентификации доступа HTTP объясняется в «HTTP-аутентификации: Basic и Digest Authentication Access».
Wikipedia
Для доступа к запрашиваемому ресурсу требуется аутентификация.
В заголовке ответ должен содержать поле WWW-Authenticate с перечнем условий аутентификации.
Клиент может повторить запрос, включив в заголовок сообщения поле Authorization с требуемыми для
аутентификации данными.
Код используется для пропущенного или не корректного токена аутентификации.
402: Payment
Required
Этот код зарезервирован для использования в будущем.
Wikipedia
Предполагается использовать в будущем.
В настоящий момент не используется.
Этот код предусмотрен для платных пользовательских сервисов, а не для хостинговых компаний.
Имеется в виду, что эта ошибка не будет выдана хостинговым провайдером в случае просроченной оплаты его
услуг.
Зарезервирован, начиная с HTTP/1.1.
* 403: Forbidden
Сервер понял запрос, но отказывается его обрабатывать. Авторизация не поможет и этот запрос
НЕ СЛЕДУЕТ повторять. Если метод запроса был HEAD и сервер хочет указать причину,
почему запрос не был обработан, то ему СЛЕДУЕТ включить в ответ сообщение с объяснением. Если
сервер не хочет, чтобы эта информация была доступна клиенту, вместо кода 403 можно
использовать 404.
Wikipedia
Сервер понял запрос, но он отказывается его выполнять из-за ограничений в доступе для клиента к указанному
ресурсу.
Если для доступа к ресурсу требуется аутентификация средствами HTTP, то сервер вернёт ответ 401 или 407 при
использовании прокси.
В противном случае ограничения были заданы администратором сервера или разработчиком веб-приложения
и могут быть любыми в зависимости от возможностей используемого программного обеспечения.
В любом случае клиенту следует сообщить причины отказа в обработке запроса.
Наиболее вероятными причинами ограничения может послужить попытка доступа к системным ресурсам веб-сервера
(например, файлам .htaccess или .htpasswd) или к файлам, доступ к которым был закрыт с помощью
конфигурационных файлов,
требование аутентификации не средствами HTTP, например, для доступа к системе управления содержимым или
разделу
для зарегистрированных пользователей либо сервер не удовлетворён IP-адресом клиента, например, при
блокировках.
Появился в HTTP/1.0.
Код ошибки используется для ответа пользователю, у которого нет
прав для совершения этой операции или если ресурс не доступен по какой-то причине (например,
из-за временного ограничения).
* 404: Not Found
Сервер не нашёл по указанному URI никаких ресурсов. Нет никаких указаний о том, постоянное
это состояние или нет. СЛЕДУЕТ использовать статус 410 (Gone), если серверу известно, что
старый ресурс недоступен постоянно и у него нет адреса пересылки. Этот статус часто используют
тогда, когда сервер не хочет обнаруживать истинную причину того, почему он не обработал
запрос, или если нельзя применить никакой другой запрос.
Wikipedia
Самая распространённая ошибка при пользовании Интернетом, основная причина — ошибка в написании адреса
Web-страницы.
Сервер понял запрос, но не нашёл соответствующего ресурса по указанному URI.
Если серверу известно, что по этому адресу был документ, то ему желательно использовать код 410.
Ответ 404 может использоваться вместо 403, если требуется тщательно скрыть от посторонних глаз определённые
ресурсы.
Появился в HTTP/1.0.
Используется тогда, когда ресурс не был найден, не существует или был 401, или 403, но из
соображений безопасности сервер не ответил этими кодами.
405: Method Not
Allowed
Выполнение метода, определенного в запросе, не разрешено для ресурса, идентифицированного конкретным
адресом.
Ответ должен содержать Allow заголовок, со списком разрешенных методов для запрашиваемого ресурса.
Wikipedia
Указанный клиентом метод нельзя применить к текущему ресурсу.
В ответе сервер должен указать доступные методы в заголовке Allow, разделив их запятой.
Эту ошибку сервер должен возвращать, если метод ему известен, но он не применим именно к указанному в
запросе ресурсу,
если же указанный метод не применим на всём сервере, то клиенту нужно вернуть код 501 (Not Implemented).
Появился в HTTP/1.1.
406: Not
Acceptable
Ресурс, определяемый запросом, может только формировать ответы, имеющие характеристики,
не совместимые с принятыми заголовками, которые были отправлены в запросе.
Если глагол запроса был не HEAD, в ответ СЛЕДУЕТ включить список доступных характеристик
сущности и их места расположения, из которых пользователь или агент пользователя может
выбрать наиболее приемлемый вариант. Формат сущности указан в заголовке Content-Type.
В зависимости от формата и возможностей агента пользователя, выбор наиболее приемлемого
варианта МОЖЕТ происходить автоматически. Как бы то ни было, эта спецификация не определяет
каких-либо стандартов для автоматической выборки.
Заметьте: Сервера HTTP/1.1 могут возвращать ответы, неприемлемые для запроса с
указанными заголовками. В некоторых случаях предпочтительнее возвращать статус 406. Такое
поведение поощряет пользователя проверять заголовки запроса и определять, является ли
запрос приемлемым.
Если ответ был не приемлемым, агенту пользователя СЛЕДУЕТ временно прекратить получение других
данных и запросить у пользователя решение для дальнейших действий.
Wikipedia
Запрошенный URI не может удовлетворить переданным в заголовке характеристикам.
Если метод был не HEAD, то сервер должен вернуть список допустимых характеристик для данного ресурса.
Появился в HTTP/1.1.
407: Proxy
Authentication Required
Этот код, аналогичен 401 (Unauthorized), но отражает то, что пользователь должен сначала авторизоваться
через прокси.
Прокси-сервер должен вернуть Proxy-Authenticate заголовок (раздел 14.33), содержащий запрос ресурса.
Клиент может повторить запрос вместе с Proxy-Authenticate заголовком (раздел 14.34).
HTTP доступ рассмотрен в «HTTP Authentication: Basic and Digest Access Authentication»
Wikipedia
Ответ аналогичен коду 401, за исключением того, что аутентификация производится для прокси-сервера.
Механизм аналогичен идентификации на исходном сервере.
Появился в HTTP/1.1.
408: Request
Timeout
Клиент не предоставил запрос за то время, пока сервер был готов его ждать. Клиент МОЖЕТ
повторить запрос без изменений в любое время.
Wikipedia
Время ожидания сервером передачи от клиента истекло.
Клиент может повторить запрос, аналогичный предыдущему, в любое время.
Например, такая ситуация может возникнуть при загрузке на сервер объёмного файла методом POST или PUT.
В какой-то момент передачи источник данных перестал отвечать, например,
из-за повреждения компакт-диска или потери связи с другим компьютером в локальной сети.
Пока клиент ничего не передаёт, ожидая от него ответа, соединение с сервером держится.
Через некоторое время сервер может закрыть соединение со своей стороны, чтобы дать возможность другим
клиентам сделать запрос.
Этот ответ не возвращается, когда клиент принудительно остановил передачу по команде пользователя или
соединение прервалось по каким-то иным причинам,
так как ответ уже послать невозможно.
Появился в HTTP/1.1.
* 409: Conflict
Запрос нельзя обработать из-за конфликта в текущем состоянии ресурса. Этот код разрешается
использовать только в тех случаях, когда ожидается, что пользователь может самостоятельно
разрешить этот конфликт и повторить запрос. В тело ответа СЛЕДУЕТ включить достаточное
количество информации для того, чтобы пользователь смог понять причину конфликта. В идеале
ответ должен содержать такую информацию, которая поможет пользователю или его агенту
исправить проблему. Однако это не всегда возможно и это не обязательно.
Как правило, конфликты происходят во время PUT-запроса. Например, во время использования
версионирования, если сущность, к которой обращаются методом PUT, содержит изменения,
конфликтующие с теми, что были сделаны ранее третьей стороной, серверу следует использовать
ответ 409, чтобы дать понять пользователю, что этот запрос нельзя завершить. В этом случае
в ответной сущности должен содержаться список изменений между двумя версиями в формате,
который указан в поле заголовка Content-Type.
Wikipedia
Запрос не может быть выполнен из-за конфликтного обращения к ресурсу.
Такое возможно, например, когда два клиента пытаются изменить ресурс с помощью метода PUT.
Появился в HTTP/1.1.
Whenever a resource conflict would be caused by fulfilling the request. Duplicate
entries and deleting root objects when cascade-delete is not supported are a couple of examples.
410: Gone
Требуемый ресурс больше не доступен на сервере и адрес его расположения неизвестен.
Предполагается, что это состояние постоянно. Клиентам с возможностью редактирования ссылки
СЛЕДУЕТ удалить ссылки на запрошенный URL после подтверждения. Если сервер не знает, или
у него нет возможности определить, постоянно это состояние или нет, СЛЕДУЕТ использовать
статус 404 (Not Found). Этот ответ можно кэшировать до тех пор, пока не появится другая
информация.
Ответ 410, в первую очередь, предназначен для помощи в оповещении получателей о том, что
ресурс умышленно недоступен и что владельцы сервера хотят, чтобы все удаленные ссылки на
ресурс были удалены. Такая ситуация обычна для рекламных серверов и для частных ресурсов,
владельцы которых больше не поддерживают сайт. Необязательно помечать все постоянно
недоступные ресурсы «пропавшими» или сохранять такую пометку на какое-то время — это
остаётся на усмотрение владельца.
Wikipedia
Такой ответ сервер посылает, если ресурс раньше был по указанному URL, но был удалён и теперь недоступен.
Серверу в этом случае неизвестно и местоположение альтернативного документа, например, копии.
Если у сервера есть подозрение, что документ в ближайшее время может быть восстановлен, то лучше клиенту
передать код 404.
Появился в HTTP/1.1.
411: Length Required
Сервер отказывается принять запрос без указания Content-Length. Клиент МОЖЕТ повторить
запрос, если добавит корректное значение в поле заголовка Content-Length, которое содержит
длину тела сообщения в сообщении запроса.
Wikipedia
Для указанного ресурса клиент должен указать Content-Length в заголовке запроса.
Без указания этого поля не стоит делать повторную попытку запроса к серверу по данному URI.
Такой ответ естественен для запросов типа POST и PUT.
Например, если по указанному URI производится загрузка файлов, а на сервере стоит ограничение на их объём.
Тогда разумней будет проверить в самом начале заголовок Content-Length и сразу отказать в загрузке,
чем провоцировать бессмысленную нагрузку, разрывая соединение,
когда клиент действительно пришлёт слишком объёмное сообщение.
Появился в HTTP/1.1.
412:
Precondition Failed
Предварительное условие, указанное в одном или нескольких заголовках запроса, оказалось
ложным, когда оно проверялось на сервере. Этот код ответа позволяет клиенту записывать
предварительные условия в метаинформации текущего ресурса, таким образом, предотвращая
применение запрошенного метода к ресурсу, кроме того, что ожидается.
Wikipedia
Возвращается, если ни одно из условных полей заголовка запроса не было выполнено.
413:
Request Entity Too Large
Возвращается в случае, если сервер отказывается обработать запрос по причине слишком большого размера тела
запроса. Сервер может закрыть соединение, чтобы прекратить дальнейшую передачу запроса.
Если проблема временная, то рекомендуется в ответ сервера включить заголовок Retry-After с указанием
времени, по истечении которого можно повторить аналогичный запрос.
Wikipedia
Тело запроса больше, чем сервер может обработать.
414:
Request-URI Too Long
Сервер не может обработать запрос из-за слишком длинного указанного URL. Эту редкую ошибку
можно спровоцировать, например, когда клиент пытается передать длинные параметры через метод
GET, а не POST, когда клиент попадает в «чёрную дыру» перенаправлений (например, когда префикс URI
указывает на своё же окончание), или когда сервер подвергается атаке со стороны клиента,
который пытается использовать дыры в безопасности, которые встречаются на серверах с
фиксированной длиной буфера для чтения или обработки Request-URI.
Wikipedia
Указанный URI был слишком длинным и сервер не смог его обработать.
416:
Requested Range Not
Satisfiable
Серверу следует вернуть ответ с этим кодом, если запрос содержал поле заголовка Range
и ни одно из его значений не совпало с размером выбранного ресурса, при этом в запросе не
было поля заголовка If-Range. (Для байтовых диапазонов (byte-range) это означает, что
значение first-byte-pos в спецификации byte-range-spec было больше, чем фактический размер
выбранного ресурса.)
Когда этот статус возвращается в ответ на запрос с указанием диапазона запрашиваемых байт
(byte-range requests), в ответ СЛЕДУЕТ включить поле заголовка сущности Content-Range,
в котором указать фактический размер ресурса (см. секцию 14.16). Этот ответ НЕЛЬЗЯ
использовать при передаче типа multipart/byteranges.
Wikipedia
Клиент запросил часть файла, но сервер не может её передать. Например, если клиент запросил
часть файла, которая находится за пределами конца файла.
417: Expectation
Failed
Сервер не может удовлетворить значению поля Expect заголовка запроса (см. секцию 14.20), или,
если он является прокси-сервером, у него есть однозначное доказательство того, что сервер следующего
уровня не сможет удовлетворить этот запрос.
Wikipedia
Сервер не может удовлетворить значению поля Expect заголовка запроса.
418: I’m a teapot (RFC
2324)
Wikipedia
418: Я — чайник
Этот код был введен в 1998 году как одна из традиционных первоапрельских шуток IETF в RFC 2324,
Hyper Text Coffee Pot Control Protocol. Не ожидается, что данный код будет поддерживаться
реальными серверами. Как бы то ни было, реализации существуют. HTTP сервер Nginx
в своей конфигурации использует этот код для имитации goto-подобного поведения.
420: Enhance Your
Calm (Twitter)
Wikipedia
Возвращается Twitter Search и Trends API, когда клиент отправляет слишком много запросов.
Вероятно, номер этого кода — отсылка к
культуре
употребления марихуаны
Другие сервисы используют вместо этого кода статус 429 Too Many Requests.
422:
Unprocessable Entity (WebDAV)
Ответ 422 (Unprocessable Entity) означает, что сервер понимает указанный вид данных,
(следовательно, статус 415 (Unsupported Media Type) не подходит), и синтаксис запроса
корректен (поэтому статус 400 (Bad Request) не подходит), но содержащиеся в запросе
инструкции нельзя выполнить. Например, эта ошибка может возникнуть, если тело запроса
было синтаксически правильным, но содержало семантическую ошибку.
Wikipedia
Запрос имел правильный формат, но его нельзя обработать из-за семантических ошибок.
423: Locked (WebDAV)
Статус 423 значит, что целевой ресурс недоступен для указанного метода. Этот ответ
ДОЛЖЕН содержать соответствующее предусловие или постусловие, например
‘lock-token-submitted’ или ‘no-conflicting-lock’
Wikipedia
Целевой ресурс из запроса заблокирован от применения к нему указанного метода. Введено в WebDAV.
424: Failed
Dependency (WebDAV)
Код 424 (Failed Dependency) значит, что метод невозможно применить к ресурсу, потому что
запрошенное действие зависело от другого действия, выполнить которое не удалось. Например,
если не удалось выполнить команду с методом PROPPATCH, то, как минимум, все остальные
запросы завершатся со статусом 424 (Failed Dependency).
Wikipedia
Не удалось завершить запрос из-за ошибок в предыдущем запросе. (например, PROPPATCH)
425:
Reserved for WebDAV
Slein, J., Whitehead, E.J., и др., «WebDAV Advanced Collections Protocol», Работа в процессе.
Wikipedia
Определен в проекте «WebDAV Advanced Collections Protocol», но не присутствует в «Web
Distributed Authoring and Versioning (WebDAV) Ordered Collections Protocol».
426: Upgrade
Required
Для надёжного согласования функций обновления с возможностью взаимодействия требуется однозначный сигнал
отказа.
Код состояния 426 Upgrade Required позволяет серверу окончательно указать, с какими именно расширениями
протокола должен обслуживаться данный ресурс.
Wikipedia
Клиенту следует выбрать другой протокол, например такой, как TLS/1.0.
428:
Precondition Required
Код состояния 428 указывает, что исходный сервер требует, чтобы запрос был условным.
Его типичное использование — избежать проблемы «потерянного обновления», когда клиент ПОЛУЧАЕТ состояние
ресурса, изменяет его и ОТПРАВЛЯЕТ обратно на сервер, когда тем временем третья сторона изменила состояние
на сервере, что привело к конфликту. Требуя, чтобы запросы были условными, сервер может гарантировать, что
клиенты работают с правильными копиями.
Ответы с этим кодом состояния ДОЛЖНЫ объяснять, как повторно отправить запрос.
Код состояния 428 не является обязательным; клиенты не могут полагаться на его использование, чтобы
предотвратить конфликты «потерянных обновлений».
Wikipedia
Исходный сервер требует, чтобы запрос был условным. Предназначен для предотвращения проблемы
«потерянного обновления», когда клиент ПОЛУЧАЕТ состояние ресурса, изменяет его и отправляет
обратно на сервер, когда тем временем третья сторона изменила состояние на сервере, что привело к конфликту.
429: Too Many
Requests
Код состояния 429 указывает, что пользователь отправил слишком много запросов за заданный промежуток
времени («ограничение скорости»).
Представления ответа ДОЛЖНЫ включать подробности, объясняющие условие, и МОГУТ включать заголовок
Retry-After, указывающий, как долго ждать, прежде чем делать новый запрос.
Когда сервер находится под атакой или просто получает очень большое количество запросов от одной стороны,
ответ на каждый с кодом состояния 429 потребляет ресурсы.
Следовательно, серверы не обязаны использовать код состояния 429; при ограничении использования ресурсов
может быть более целесообразным просто разорвать соединение или предпринять другие шаги.
Wikipedia
Пользователь отправил слишком много запросов за заданный промежуток времени. Предназначен для использования
со схемами ограничения скорости.
444: No Response
(Nginx)
Wikipedia
Код ответа Nginx.
Сервер не вернул информацию и закрыл соединение.
(полезно в качестве сдерживающего фактора для вредоносных программ)
449: Retry With
(Microsoft)
Wikipedia
Расширение Microsoft. Запрос следует повторить после выполнения соответствующего действия.
450:
Blocked by Windows Parental Controls
(Microsoft)
Wikipedia
Расширение Microsoft. Эта ошибка возникает, когда родительский контроль Windows включён и блокирует доступ
к данной веб-странице.
451:
Unavailable For Legal Reasons
Доступ к ресурсу закрыт по юридическим причинам. Наиболее близким из существующих является
код 403 Forbidden (сервер понял запрос, но отказывается его обработать). Однако в случае
цензуры, особенно когда это требование к провайдерам заблокировать доступ к сайту, сервер
никак не мог понять запроса — он его даже не получил. Совершенно точно подходит другой код:
305 Use Proxy. Однако такое использование этого кода может не понравиться цензорам. Было
предложено несколько вариантов для нового кода, включая «112 Emergency. Censorship in
action» и «460 Blocked by Repressive Regime»
Wikipedia
Доступ к ресурсу закрыт по юридическим причинам, например, по требованию органов
государственной власти или по требованию правообладателя в случае нарушения авторских прав.
Введено в черновике IETF за авторством Google, при этом код ошибки является отсылкой
к роману Рэя Брэдбери «451 градус по Фаренгейту».
499: Client
Closed Request (Nginx)
Wikipedia
Код используется Nginx. Этот код был введен для логирования ситуаций, когда клиент закрывает соединение
во время обработки запроса сервером. Таким образом, сервер не может отправить назад заголовок HTTP.
5xx: Server
Error
Коды ответов, начинающиеся с «5» указывают на случаи, когда сервер знает, что произошла ошибка
или он не может обработать запрос. Кроме HEAD-запросов, серверу следует включить в ответ сущность,
содержащую объяснение ошибки, и является ли это временным или постоянным состоянием. Агентам СЛЕДУЕТ
показывать включённую сущность пользователям. Этот код ответа подходит для любых методов запросов.
Wikipedia
Сервер не смог выполнить явно корректный запрос.
Коды 5xx выделены под случаи неудачного выполнения операции по вине сервера. Для всех ситуаций, кроме
использования метода HEAD, сервер должен включать в тело сообщения объяснение, которое клиент отобразит
пользователю. Эти коды ответа подходит для любых методов запросов.
* 500:
Internal Server
Error
Сервер столкнулся с неожиданными условиями, которые не позволили ему обработать запрос.
Wikipedia
Универсальное сообщение о внутренней ошибке сервера, когда никакое более определенное сообщение не
подходит.
Универсальный код ошибки, когда на стороне сервера произошло исключение.
501: Not
Implemented
Сервер не поддерживает функциональных возможностей, необходимых для выполнения запроса.
Это типичный ответ, когда сервер не понимает метод в запросе и не способен выполнить запрос для ресурса.
Если же метод серверу известен, но он не применим к данному ресурсу, то нужно вернуть ответ 405.
Появился в HTTP/1.0.
Wikipedia
Серверу либо неизвестен метод запроса, или ему (серверу) не хватает возможностей выполнить запрос.
502: Bad Gateway
Сервер, выступая в роли шлюза или прокси-сервера, получил некорректный ответ от вышестоящего сервера,
к которому он обратился для выполнения запроса. Появился в HTTP/1.0.
Wikipedia
Сервер, выступая в роли шлюза или прокси-сервера, получил некорректный ответ от вышестоящего сервера.
503: Service
Unavailable
Сервер не может обработать запрос из-за временной перегрузки или технических работ. Это временное
состояние, из которого сервер выйдет через какое-то время. Если это время известно, то его МОЖНО
передать в заголовке Retry-After. Если заголовок Retry-After передан, то клиенту СЛЕДУЕТ обрабатывать
ответ так, как если бы ответом был статус 500.
Замечание: существование кода 503 не обязывает сервер отвечать этим статусом, когда он перегружен. Некоторые
сервера просто отвергают соединения.
Wikipedia
Сервер недоступен (из-за перегрузки или технических работ). Обычно это временное состояние.
504: Gateway
Timeout
Сервер, в роли шлюза или прокси-сервера, не дождался в рамках установленного таймаута ответа от
вышестоящего сервера текущего запроса.
Замечание: Некоторые прокси-сервера возвращают 400 или 500,
когда время обработки DNS запроса превышает установленный таймаут.
Wikipedia
Сервер в роли шлюза или прокси-сервера не дождался ответа от вышестоящего сервера для завершения текущего
запроса. Появился в HTTP/1.1.
505: HTTP
Version Not Supported
Сервер не поддерживает или отказывается поддерживать версию протокола HTTP, которая использовалась в
сообщении запроса. Сервер указывает, что он не может или не хочет выполнить запрос, используя ту же основную
версию, что и клиент, как описано в разделе 3.1, за исключением этого сообщения об ошибке. Ответ ДОЛЖЕН
содержать сущность, описывающую, почему эта версия не поддерживается, и какие другие протоколы
поддерживаются этим сервером.
Wikipedia
Сервер не поддерживает или отказывается поддерживать указанную в запросе версию протокола HTTP. Появился в
HTTP/1.1.
506: Variant
Also Negotiates (Experimental)
Код состояния 506 указывает на то, что сервер имеет внутреннюю ошибку конфигурации: выбранный вариант
ресурса настроен для участия в прозрачном согласовании содержимого и, следовательно, не является надлежащей
конечной точкой в процессе согласования.
Wikipedia
В результате ошибочной конфигурации выбранный вариант указывает сам на себя,
из-за чего процесс связывания прерывается.
Экспериментальное.
Введено в RFC 2295 для дополнения протокола HTTP технологией Transparent Content Negotiation.
507:
Insufficient Storage (WebDAV)
Код состояния 507 (Переполнение хранилища) означает, что метод не может быть выполнен для ресурса,
поскольку сервер не может сохранить представление, необходимое для успешного выполнения запроса. Это
состояние считается временным. Если запрос, получивший этот код состояния, был результатом действия
пользователя, запрос НЕ ДОЛЖЕН повторяться до тех пор, пока он не будет запрошен отдельным действием
пользователя.
Wikipedia
Не хватает места для выполнения текущего запроса. Проблема может быть временной. Введено в WebDAV.
508: Loop Detected
(WebDAV)
Код состояния 508 (обнаружен цикл) указывает, что сервер завершил операцию, поскольку он обнаружил
бесконечный цикл при обработке запроса с «Depth: infinity». Этот статус указывает на то, что вся
операция завершилась неудачно.
Wikipedia
Сервер обнаружил бесконечный цикл при обработке запроса.
509:
Bandwidth Limit Exceeded (Apache)
Wikipedia
Используется при превышении веб-площадкой отведённого ей ограничения на потребление трафика.
В данном случае владельцу площадки следует обратиться к своему хостинг-провайдеру.
В настоящий момент данный код не описан ни в одном RFC и используется только модулем «bw/limited»,
входящим в панель управления хостингом cPanel, где и был введён.
510: Not Extended
В запросе не соблюдена политика доступа к ресурсу. Сервер должен отправить обратно всю информацию,
необходимую клиенту для отправки расширенного запроса. Указание того, как расширения информируют клиента,
выходит за рамки данной спецификации.
Если ответ 510 содержит информацию о расширениях, которые не присутствовали в начальном запросе, тогда
клиент МОЖЕТ повторить запрос, если у него есть основания полагать, что он может выполнить политику
расширений, изменив запрос в соответствии с информацией, предоставленной в ответе 510. В противном случае
клиент МОЖЕТ представить пользователю любой объект, включённый в ответ 510, поскольку этот объект может
включать в себя релевантную диагностическую информацию.
Wikipedia
На сервере отсутствует расширение, которое желает использовать клиент.
Сервер может дополнительно передать информацию о доступных ему расширениях.
Введено в RFC 2774 для дополнения протокола HTTP поддержкой расширений
511: Network
Authentication Required
511 код ответа означает, что клиенту необходима авторизация для получения доступа к сети.
Ответ должен содержать ссылку на ресурс, на котором пользователь сможет авторизоваться (например с HTML
формой)
Упоминание о том, что 511 ответ не должен содержать требования авторизации или соответствующего интерфейса,
потому что браузеры должны будут отобразить интерфейс авторизации, который будет ассоциироваться с
запрашиваемым URL,
что может путать пользователя.
Статус 511 НЕ ДОЛЖЕН генерироваться исходными серверами; он предназначен для использования путём перехвата
прокси-серверов, которые вставляются в качестве средства контроля доступа к сети.
Ответы с кодом состояния 511 НЕ ДОЛЖНЫ храниться в кэше.
Код состояния 511 разработан для смягчения проблем, вызванных «перехватывающими порталами» для программного
обеспечения (особенно агентов, не являющихся браузерами), которое ожидает ответа от сервера, к которому был
сделан запрос, а не от промежуточной сетевой инфраструктуры. Он не предназначен для поощрения развёртывания
скрытых порталов, а только для ограничения наносимого ими ущерба.
Сетевой оператор, желающий потребовать некоторой аутентификации, принятия условий или другого
взаимодействия с пользователем перед предоставлением доступа, обычно делает это путём идентификации
клиентов, которые этого не сделали («неизвестные клиенты»), используя свои MAC-адреса.
Неизвестные клиенты затем блокируют весь трафик, за исключением TCP-порта 80, который отправляется на
HTTP-сервер («сервер входа в систему»), предназначенный для «входа в систему» неизвестных
клиентов, и, конечно же, трафик на сам сервер входа в систему.
Обычно ответ, содержащий код состояния 511, не поступает от исходного сервера, указанного в URL-адресе
запроса. Это создаёт множество проблем с безопасностью; например, атакующий посредник может вставлять файлы
cookie в пространство имён исходного домена, может наблюдать файлы cookie или учетные данные
HTTP-аутентификации, отправленные пользовательским агентом, и так далее.
Однако эти риски не уникальны для кода состояния 511; другими словами, адаптивный портал, который не
использует этот код состояния, вызывает те же проблемы.
Также обратите внимание, что связанные порталы, использующие этот код состояния при подключении SSL или TLS
(обычно порт 443), будут генерировать ошибку сертификата на клиенте.
Wikipedia
Этот ответ посылается не сервером, которому был предназначен запрос,
а сервером-посредником — например, сервером провайдера — в случае,
если клиент должен сначала авторизоваться в сети, например,
ввести пароль для платной точки доступа к Интернету.
Предполагается, что в теле ответа будет возвращена Web-форма авторизации или перенаправление на неё.
Введено в черновике стандарта RFC 6585
598: Network
read timeout error
Wikipedia
Этот статус не описан в стандарте, однако может быть использован некоторыми HTTP прокси.
599: Network
connect timeout error
Wikipedia
Этот статус не описан в стандарте, однако может быть использован некоторыми HTTP прокси.
*
«Top 10» HTTP код ответа. Дополнительная информация о службе REST содержится в
записи.