Коды состояния HTTP

Коды состояния HTTP — трёхзначные числа в первой строке ответа HTTP-сервера, которые сообщают клиенту результат обработки запроса: успех, перенаправление, ошибка клиента или ошибка сервера. Рядом с кодом идёт короткая поясняющая фраза (reason phrase), например 404 Not Found, но программы ориентируются только на число. Коды определены в RFC 9110, а полный перечень ведёт IANA.^[1][2]

Правильно выбранный код важен для API (REST), кэширования, поисковых систем и мониторинга: по доле ответов 5xx судят о здоровье сервиса.

Классы

Первая цифра задаёт класс ответа. Клиент, не знающий конкретного кода, обязан обработать его как код x00 своего класса — например, неизвестный 599 как 500.

Основные коды

1xx и 2xx

3xx

Исторически браузеры при 301 и 302 меняли POST на GET; коды 307 и 308 введены, чтобы метод гарантированно сохранялся.

4xx

Код 451 — отсылка к роману Брэдбери «451 градус по Фаренгейту». Шуточный код 418 I'm a teapot («Я чайник») появился в первоапрельском RFC 2324 (1998) и стал частью веб-фольклора.

5xx

Коды 502 и 504 обычно возвращает не само приложение, а обратный прокси вроде nginx: они означают, что бэкенд упал, недоступен или отвечает слишком долго.

Как выбирать код в API

• 401 или 403? 401 — клиент не представился или токен недействителен; повторить с правильными учётными данными. 403 — клиент известен, но действие ему запрещено.
• 400 или 422? 400 — запрос нельзя разобрать (сломанный JSON); 422 — разобрать можно, но значения неверны (email без @). Многие фреймворки, например FastAPI, возвращают 422 при ошибке проверки данных.
• 404 вместо 403 иногда возвращают сознательно, чтобы не раскрывать само существование закрытого ресурса.
• Не возвращайте 200 с ошибкой в теле ({"ok": false}): это ломает кэширование, мониторинг и повторы на стороне клиента.
• Повторять запрос автоматически имеет смысл при 429, 502, 503 и 504 — с паузой и экспоненциальной задержкой, но не при 4xx, означающих ошибку в самом запросе.

Подробности ошибки в API принято передавать в стандартном формате Problem Details (RFC 9457) с типом содержимого application/problem+json:^[6]

{
  "type": "https://example.com/errors/insufficient-funds",
  "title": "Недостаточно средств",
  "status": 409,
  "detail": "На счёте 30 ₽, требуется 50 ₽."
}

Проверка кода ответа

curl -s -o /dev/null -w '%{http_code}\n' https://example.com   # только код
curl -I https://example.com/old-page                           # заголовки, включая Location

Справочник с описанием каждого кода и примерами есть на MDN.^[3] Утилита curl с флагом -f завершается ошибкой при кодах от 400, что удобно в скриптах.

См. также

• HTTP
• REST
• curl
• Обратный прокси (reverse proxy)

Источники

1. RFC 9110 — HTTP Semantics, Section 15: Status Codes
2. IANA — HTTP Status Code Registry
3. MDN — HTTP response status codes
4. RFC 6585 — Additional HTTP Status Codes (428, 429, 431, 511)
5. RFC 7725 — An HTTP Status Code to Report Legal Obstacles (451)
6. RFC 9457 — Problem Details for HTTP APIs