Какой статус кода будет при ответе на запрос для получения отчетов?

Статус коды HTTP при получении отчетов: стратегия выбора

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

Ответ зависит от контекста запроса, состояния ресурса и бизнес-логики. Вот детальный разбор наиболее вероятных сценариев.

Основные успешные статус-коды (2xx)

• 200 OK — Успешное получение отчета.

    Это самый распространенный и ожидаемый ответ. Сервер успешно нашел запрошенный отчет (или список отчетов) и возвращает его в теле ответа. Формат данных (JSON, XML, CSV, PDF) обычно определяется заголовком `Accept` запроса или параметром запроса.

```http
HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "rep_12345",
  "name": "Sales Q1 2024",
  "generatedAt": "2024-03-31T10:30:00Z",
  "data": { ... }
}
```

• 202 Accepted — Запрос на генерацию принят, отчет готовится.

    Используется для **асинхронных** операций, когда отчет не готов немедленно, а требует длительной обработки (сбор данных из нескольких систем, сложные вычисления). Сервер принимает запрос в работу, но тело ответа пустое или содержит ссылку для отслеживания статуса (например, в заголовке `Location`).

```http
HTTP/1.1 202 Accepted
Location: /api/reports/status/rep_12345
Retry-After: 120
```

• 206 Partial Content — Частичное содержимое.

    Актуально для реализации **пагинации** или потоковой загрузки очень больших отчетов. Сервер возвращает только часть данных с указанием диапазона (через заголовки `Content-Range` или в теле).

```http
HTTP/1.1 206 Partial Content
Content-Range: bytes 0-999/5000
```

Статус-коды перенаправления (3xx)

• 303 See Other или 302 Found — Отчет доступен по другому URL.

    Если отчет — это статический файл (PDF, Excel), который был сгенерирован ранее и сохранен в объектном хранилище (S3), сервер может вернуть один из этих кодов с заголовком `Location`, указывающим на прямой URL файла.

Статус-коды клиентских ошибок (4xx)

• 400 Bad Request — Неверный синтаксис запроса.

    Клиент отправил запрос с ошибками: неверные или отсутствующие обязательные параметры фильтрации (`?dateFrom=...`), некорректный формат даты, невалидный JSON в теле запроса (если отчет создается "на лету" по параметрам).

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Parameter 'dateFrom' must be a valid ISO 8601 date."
  }
}
```

• 401 Unauthorized — Требуется аутентификация.

    Запрос не содержит учетных данных (токена, куки) или они недействительны.

• 403 Forbidden — Доступ запрещен.

    Пользователь аутентифицирован, но у него нет прав на просмотр запрошенного отчета (например, отчет из другого департамента).

• 404 Not Found — Отчет не найден.

    Запрашиваемого отчета с указанным ID не существует в системе, или он был удален. **Важно:** если отчет еще не сгенерирован, но может быть создан, иногда более уместен `404`, а иногда — отдельный статус или бизнес-логика в `200` с полем `status: "pending"`.

• 409 Conflict — Конфликт состояния.

    Может возникать, если клиент пытается повторно запустить генерацию отчета, которая уже выполняется, и это запрещено логикой.

Статус-коды серверных ошибок (5xx)

• 500 Internal Server Error — Общая ошибка сервера.

    Произошла непредвиденная ошибка при обработке запроса (исключение в коде, сбой базы данных).

• 503 Service Unavailable — Сервис недоступен.

    Сервер временно не может обработать запрос из-за перегрузки или технического обслуживания. Заголовок `Retry-After` может указать, когда повторить попытку.

Практические рекомендации и вывод

1. Консистентность. Важнее всего последовательно применять выбранные статус-коды во всем API.
2. Семантика превыше всего. Используйте коды по их прямому назначению согласно RFC. Не возвращайте 200 с ошибкой в теле.
3. Детализация в теле ответа. Для ошибок 4xx и 5xx всегда возвращайте в теле JSON с человекочитаемым сообщением, кодом ошибки и, при возможности, ссылкой на документацию.
4. Сценарий для 204 No Content. Может использоваться, если запрос на удаление отчета успешен, но для получения это менее типично.

Итоговый ответ: для успешного запроса на получение уже готового отчета по его ID наиболее правильным и ожидаемым статусом является 200 OK. Для запроса на запуск создания нового сложного отчета уместен 202 Accepted. Все остальные коды сигнализируют о конкретных проблемах на стороне клиента (400, 403, 404) или сервера (500, 503), которые клиентское приложение должно корректно обрабатывать.