HTTP классы статусов: 2xx коды успеха и 4xx ошибки клиента

Этот материал объясняет HTTP классы статусов с примерами и контрольными вопросами.

Краткое резюме

• 2xx: успешная обработка запроса (200 OK, 201 Created, 202 Accepted, 204 No Content)
• 4xx: ошибки, вызванные клиентом (400, 401, 403, 404, 409, 422, 429)

Справочное описание

2xx указывает на успешную обработку запроса, 4xx обозначает ошибки со стороны клиента. В группу 2xx входят типичные успехи: 200 OK для операций чтения, 201 Created с заголовком Location для новых ресурсов, 202 Accepted для асинхронно запущенных операций, 204 No Content когда телo ответа не требуется. 4xx описывает ошибки клиента: 400 Bad Request при ошибках валидации, 401 Unauthorized если отсутствует аутентификация, 403 Forbidden при недостатке прав доступа, 404 Not Found когда ресурс неизвестен, 409 Conflict при конфликтах версий, 422 Unprocessable Content при семантически некорректных данных, 429 Too Many Requests при превышении лимитов запросов.

Ключевые моменты для подготовки

• 201 Created всегда с заголовком Location на новый ресурс
• 204 No Content используйте только если клиенту действительно не нужно тело ответа
• 202 Accepted для асинхронных рабочих процессов с последующим endpoint’ом статуса
• Единообразная структура ошибок с Problem Details и отслеживаемым ID ошибки
• 409 Conflict при конфликтах ETag и параллельных обновлениях
• 401 для отсутствия аутентификации, 403 для отсутствия разрешения
• Правильные коды уменьшают затраты на поддержку и интеграцию
• Описывайте коды статусов и объекты ошибок в OpenAPI для каждой операции

Основные компоненты

1. Строка статуса с кодом и reason phrase
2. 2xx коды: 200, 201, 202, 204
3. 4xx коды: 400, 401, 403, 404, 409, 422, 429
4. Заголовки: Location, Retry-After, ETag, Content-Type
5. Условные запросы: If-Match, If-None-Match, If-Modified-Since
6. Правила идемпотентности для каждого метода
7. Объекты ошибок: Problem Details (type, title, status, detail, instance)
8. Пагинация в ответах 200 со ссылками (First, Prev, Next, Last)
9. Наблюдаемость: Correlation ID, Trace ID, логирование
10. Тестирование: негативные тесты, контрактные тесты, retry и конфликты ETag

Практический пример

// Создание заказа с последующим подтверждением
POST https://api.shop.de/orders
Headers: Content-Type: application/json, Idempotency-Key: abc-123
Body: { customerId: 123, items: [{ sku: "A1", qty: 2 }] }

Ответ при немедленном создании:
Status: 201 Created
Headers: Location: https://api.shop.de/orders/42, ETag: W/"7c9"
Body: { id: 42, status: "created" }

Ответ при асинхронной обработке:
Status: 202 Accepted
Headers: Location: https://api.shop.de/jobs/987, Retry-After: 10
Body: { jobId: 987, state: "queued" }

Конфликт из-за устаревшего ETag:
PUT https://api.shop.de/orders/42
Headers: If-Match: W/"7c9"
Body: { status: "confirmed" }

Сервер имеет новую версию:
Status: 412 Precondition Failed
Body: application/problem+json
{ type: "https://problems/concurrency", title: "Precondition failed", status: 412, detail: "Version mismatch", instance: "/orders/42" }

Преимущества и недостатки

Преимущества

• Ясная семантика, лучшее управление на стороне клиента
• Упрощенная обработка ошибок
• Лучшие стратегии кеширования и повторяемость
• Снижение затрат на поддержку

Недостатки

• Неправильные коды запутывают клиентов
• Затрудняют кеширование и retry’и
• Различные значения по умолчанию в фреймворках приводят к несогласованности
• Требует дополнительной осторожности в документации и тестах

Типичные контрольные вопросы (с кратким ответом)

1. Когда использовать 201 Created и какие заголовки релевантны? При создании нового ресурса, Location указывает на новый URI, ETag опционально для будущих обновлений.
2. Отличие 200 OK от 204 No Content? 200 передает представление ресурса, 204 обходится без тела, используйте 204 только если клиенту не нужно содержимое.
3. Асинхронные рабочие процессы со статус-кодами? 202 Accepted со statusendpoint’ом в заголовке Location, опционально Retry-After.
4. 401 vs 403, когда какой? 401 при отсутствии или неверной аутентификации, 403 если пользователь аутентифицирован но не имеет прав.
5. 409 Conflict в REST API? Конфликты приложения: конфликты версий, дублирующиеся ресурсы, нарушения бизнес-правил.
6. 422 вместо 400 Bad Request? 422 для синтаксически корректного но семантически невалидного JSON (нарушения доменных правил).
7. ETag и If-Match для безопасных обновлений? Клиент отправляет If-Match, сервер выполняет обновление только при совпадении тега, иначе 412.
8. Идемпотентность при статус-кодах и retry’ах? Идемпотентные методы (PUT, DELETE) допускают retry’и, POST требует Idempotency-Key.

Дальше в пути обучения API

Следующий материал в пути обучения API рассматривает HTTP/2 и HTTP/3: обзор протоколов — развитие HTTP-протокола с мультиплексированием, QUIC и улучшенной производительностью.

Основные источники

1. https://www.rfc-editor.org/rfc/rfc9110
2. https://developer.mozilla.org/docs/Web/HTTP/Status
3. https://www.rfc-editor.org/rfc/rfc7807