Какие знаешь статусы ответов с REST API?

Статусы ответов в REST API: классификация и практическое применение

В REST API статусы ответов (HTTP Status Codes) являются ключевым механизмом коммуникации между клиентом и сервером. Они стандартизированы RFC и делятся на пять классов, где первая цифра определяет категорию. Их правильное использование критически важно для построения понятного, надежного и удобного для интеграции API.

Классификация статусов по категориям

1xx: Информационные (Informational)

Эти статусы указывают на промежуточное состояние запроса. В современной веб-разработке они используются редко, чаще в контексте HTTP/2 и прокси.

• 100 Continue: Сервер готов принимать тело запроса после заголовков.
• 101 Switching Protocols: Сервер соглашается переключить протокол (например, на WebSocket).

2xx: Успешные (Success)

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

• 200 OK: "Король" успешных ответов. Запрос выполнен полностью.

// Пример ответа с 200 OK
{
  "status": "success",
  "data": { "id": 123, "name": "Example Item" }
}

• 201 Created: Указывает, что ресурс был успешно создан (обычно после POST). Ответ должен включать заголовок Location с URI нового ресурса.
• 204 No Content: Сервер успешно выполнил запрос, но не возвращает тело ответа (часто после DELETE или PUT). Клиент не должен обновлять представление ресурса.
• 206 Partial Content: Используется при частичной отправке контента (например, при потоковой передаче или для диапазонных запросов с заголовком Range).

3xx: Перенаправления (Redirection)

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

• 301 Moved Permanently: Ресурс перемещен на новый постоянный URI. Будущие запросы должны использовать новый URI.
• 302 Found (или 307 Temporary Redirect): Ресурс временно находится на другом URI. Клиент должен продолжать использовать исходный URI для следующих запросов.
• 304 Not Modified: Ответ на условный запрос (с заголовками If-Modified-Since или If-None-Match). Указывает, что ресурс не изменился, и клиент может использовать cached версию — тело ответа не отправляется. Это критически важно для оптимизации производительности.

4xx: Ошибки клиента (Client Error)

Ошибки по вине клиента (неверный запрос, отсутствие авторизации, конфликты). Сервер понимает запрос, но не может его выполнить.

• 400 Bad Request: Общая ошибка из-за malformed запроса (неверный синтаксис, некорректные параметры).

// Пример ответа с 400 Bad Request
{
  "error": "Validation failed",
  "details": [ { "field": "email", "message": "Invalid email format" } ]
}

• 401 Unauthorized: Запрос требует авторизации пользователя. Клиент должен предоставить valid credentials.
• 403 Forbidden: Сервер понимает запрос и клиент авторизован, но не имеет достаточных прав для действия. Различие между 401 и 403 важно для безопасности.
• 404 Not Found: Самый известный статус. Сервер не может найти указанный ресурс.
• 409 Conflict: Запрос конфликтует с текущим состоянием ресурса (например, попытка обновить ресурс с outdated версией, нарушение уникальности). Ответ должен содержать информацию для разрешения конфликта.
• 429 Too Many Requests: Клиент превысил лимит rate limiting. Сервер должен включить заголовок Retry-After.

5xx: Ошибки сервера (Server Error)

Ошибки по вине сервера, который не смог выполнить valid запрос.

• 500 Internal Server Error: Общая, "catch-all" ошибка сервера при unexpected условиях.
• 502 Bad Gateway: Сервер, выступая как прокси или gateway, получил invalid ответ от upstream сервера.
• 503 Service Unavailable: Сервер временно не может обработать запрос из-за overload или maintenance. Должен включать Retry-After, если известна длительность.
• 504 Gateway Timeout: Gateway или прокси не получил ответ от upstream сервера в allotted время.

Практические рекомендации для Frontend Developer

1. Обработка на клиенте: Необходимо корректно обрабатывать все категории, особенно 4xx и 5xx.

    *   Для 4xx ошибок показывать понятные пользователю сообщения, основанные на `error.details` из тела ответа.
    *   Для 5xx ошибок — сообщение о временной проблеме на сервере и предложение повторить попытку позже.
    *   Для 429 и 503 — соблюдать указанное в `Retry-After` время.

1. Оптимизация с 304: Используйте условные запросы для статических ресурсов (изображений, скриптов), чтобы минимизировать трафик и улучшить performance.

2. Прогнозируемое поведение API: Убедитесь, что ваш бекенд использует статусы консистентно. Например:

    *   `POST` на создание → **201 Created** с Location.
    *   `DELETE` на удаление → **204 No Content**.
    *   Неудачная валидация → **400 Bad Request** с детализацией.
    *   Отсутствие прав → **403 Forbidden** (не 401).

1. Различие между 401 и 403: В интерфейсе при 401 следует redirect на login page или показать форму авторизации. При 403 — показать сообщение о недостаточных правах.

Вывод: Глубокое понимание HTTP статусов — это не просто теория, а практический навык, необходимый для создания устойчивых frontend-приложений, которые корректно реагируют на все состояния backend, эффективно управляют кэшированием и предоставляют пользователю ясную информацию в случае ошибок. Правильное их использование значительно улучшает опыт интеграции и надежность всего приложения.