В мире веб-разработки и дизайна API коды состояния HTTP играют решающую роль в передаче результатов запросов между клиентами и серверами. Эти коды обеспечивают стандартизированный способ указания конкретных условий, успехов или ошибок, возникающих во время обработки HTTP-запросов. Понимание этих кодов состояния важно для разработчиков, поскольку оно помогает в отладке, обработке ошибок и создании более надежных приложений.

1. 1xx Информационный

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

• 100 Продолжить: сервер получил заголовки запроса, и клиент должен приступить к отправке тела запроса.
• 101 протокол переключения: запрашивающая сторона попросила сервер переключить протоколы, и сервер согласился это сделать.

2. 2хх успех

Эти коды состояния указывают на то, что запрос клиента был успешно получен, понят и принят.

• 200 OK: запрос выполнен успешно, ответ содержит запрошенные данные или результат.
  • Пример: получение информации профиля пользователя.
• 201 Создано: запрос выполнен успешно, и был создан новый ресурс.
  • Пример: создание новой учетной записи пользователя или публикация новой записи в блоге.
• 204 Нет контента: сервер успешно обработал запрос, но не возвращает никакого контента.
  • Пример: обновление настроек пользователя, при котором тело ответа не требуется.
• 206 Частичное содержимое: сервер доставляет только часть ресурса из-за заголовка диапазона, отправленного клиентом.
  • Пример: потоковое видео или загрузка больших файлов частями.

3. Перенаправление 3xx

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

• 301 Перемещено навсегда: запрошенный ресурс был окончательно перемещен на новый URL-адрес.
• 302 Найдено: запрошенный ресурс временно находится под другим URL-адресом.
• 304 Не изменен: указывает, что ресурс не был изменен с момента версии, указанной в заголовках запроса.

4. Ошибка клиента 4xx

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

• 400 неверный запрос: сервер не может обработать запрос из-за неверного синтаксиса или неверных входных данных.

  • Пример: отправка неправильного формата JSON в теле запроса.
  • Использование: используйте, когда сам запрос имеет неверный формат или содержит недопустимые параметры.

• 401 Несанкционировано: запрос требует аутентификации пользователя.

  • Пример: попытка доступа к защищенной конечной точке API без предоставления действительных учетных данных.
  • Использование: используется, когда аутентификация требуется, но не была предоставлена ​​или недействительна.

• 403 Запрещено: сервер понимает запрос, но отказывается его авторизовать.

  • Пример: пользователь пытается получить доступ к функциям, доступным только администратору.
  • Использование: используется, когда пользователь прошел аутентификацию, но не имеет разрешения на запрошенную операцию.

• 404 Не найден: запрошенный ресурс не найден на сервере.

  • Пример: попытка восстановить удаленный профиль пользователя.
  • Использование: используйте, когда запрошенный ресурс не существует.

• 405 Метод не разрешен: метод, указанный в запросе, не разрешен для ресурса, определенного URI запроса.

  • Пример: отправка запроса POST на конечную точку, которая принимает только запросы GET.

• 409 Конфликт: запрос не удалось обработать из-за конфликта с текущим состоянием ресурса.

  • Пример: попытка создать пользователя с адресом электронной почты, который уже существует в системе.
  • Использование: используйте в случае конфликта с текущим состоянием ресурса, например, при наличии повторяющихся записей.

• 422 Необрабатываемый объект: сервер понимает тип контента и синтаксис запроса, но не может обработать содержащиеся инструкции.

  • Пример: отправка формы с недопустимыми данными, которая не прошла проверку на стороне сервера.
  • Использование: используется для ошибок проверки, когда синтаксис запроса правильный, но данные семантически неверны.

• 429 Слишком много запросов: пользователь отправил слишком много запросов за определенный промежуток времени («ограничение скорости»).

  • Пример: реализация ограничения скорости API для предотвращения злоупотреблений.

5. Ошибка сервера 5xx.

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

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

  • Пример: в серверном коде возникло необработанное исключение.

• 501 Не реализовано: сервер не поддерживает функциональность, необходимую для выполнения запроса.

  • Пример: использование нового метода HTTP, который не распознается сервером.

• 502 Bad Gateway: сервер, действуя как шлюз или прокси, получил недопустимый ответ от вышестоящего сервера.

  • Пример: обратный прокси-сервер не может подключиться к исходному серверу.

• 503 Служба недоступна: сервер в настоящее время не может обработать запрос из-за временной перегрузки или технического обслуживания.

  • Пример: на сервере проводится плановое обслуживание или наблюдается высокий трафик.

• 504 Gateway Timeout: Сервер, действуя как шлюз или прокси-сервер, не получил своевременный ответ от вышестоящего сервера.

  • Пример: время ожидания ответа от стороннего API истекло.

Рекомендации по использованию кодов состояния HTTP

1. Будьте конкретны: используйте наиболее конкретный код статуса, применимый к ситуации. Это помогает клиентам точно понять, что произошло и как реагировать.

2. Последовательное использование: поддерживайте единообразие в использовании кодов состояния в вашем API. Это облегчит разработчикам работу с вашим API.

3. Предоставьте дополнительную информацию: наряду с кодом состояния включите подробное сообщение об ошибке в тело ответа, если это необходимо. Это может помочь в отладке и улучшить работу разработчиков.

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

5. Документация: четко задокументируйте, какие коды состояния использует ваш API и при каких обстоятельствах. Это помогает потребителям API понять, как интерпретировать и обрабатывать различные ответы.

Понимая и правильно реализуя коды состояния HTTP, разработчики могут создавать более надежные, понятные и удобные API и веб-приложения. Эти коды служат важным инструментом связи между клиентами и серверами, помогая упростить обработку ошибок и повысить общую надежность системы.