HTTP статус-коды 2xx и 4xx

Справочный материал по наиболее важным статус-кодам 2xx и 4xx, включая контрольные вопросы и ключевые моменты.

Суть

2xx указывает на успешную обработку. 4xx обозначает ошибки на стороне клиента. Правильное использование кодов улучшает читаемость, кеширование, идемпотентность и делает API более устойчивым.

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

Типичные 2xx:

• 200 OK (чтение/успех)
• 201 Created + Location (ресурс создан)
• 202 Accepted (асинхронный запуск)
• 204 No Content (тело отсутствует)

Типичные 4xx:

• 400 Bad Request (синтаксис/валидация)
• 401 Unauthorized (отсутствует аутентификация)
• 403 Forbidden (нет прав)
• 404 Not Found
• 409 Conflict (конфликт)
• 422 Unprocessable Content (семантически некорректно)
• 429 Too Many Requests (ограничение частоты) + Retry-After

Единообразные объекты ошибок по RFC 7807 (Problem Details) облегчают отладку и документирование.

Ключевые моменты для контроля

• 201 всегда с Location
• 204 только если действительно нет тела
• 202 + эндпоинт статуса (Location) для асинхронных операций
• 401 и 403 нужно чётко различать
• 409/412 при параллелизме/ETag
• Не включайте чувствительные данные в ошибки
• В OpenAPI задокументируйте статус-коды для каждого эндпоинта

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

1. 2xx: 200/201/202/204
2. 4xx: 400/401/403/404/409/422/429
3. Заголовки: Location, Retry-After, ETag, Content-Type
4. Условные запросы (If-Match)
5. Problem Details (type/title/status/detail/instance)
6. Тесты (негативные тесты/контрактные тесты)

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

POST /orders
→ 201 Created
Location: /orders/42
ETag: W/"7c9"

PUT /orders/42 (If-Match: W/"7c9")
→ 412 Precondition Failed при конфликте версий

GET /orders/9999
→ 404 Not Found

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

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

• Ясная семантика
• Меньше ошибок интеграции
• Лучшее поведение при кешировании и повторных попытках

Недостатки

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

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

1. Когда 201 и какой заголовок? При создании ресурса; Location указывает на новый URI.
2. 200 vs 204? 200 с телом, 204 без тела.
3. 401 vs 403? 401 означает отсутствие или неверную аутентификацию; 403 означает отсутствие прав.
4. Когда 422 вместо 400? JSON синтаксически корректен, но семантически недействителен.

Развёрнутый ответ

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

Стратегия обучения

1. Проанализируйте статус-коды публичного API.
2. Набросайте диаграмму последовательности для рабочего процесса 202.
3. Тренируйтесь на карточках (код → значение → заголовок).
4. Не используйте 200 для всего подряд.

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

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