Коды состояния HTTP: полный справочник

HTTP-коды состояния — это язык, на котором серверы сообщают клиентам о результате обработки запроса. Разработчики встречают их постоянно — в DevTools, в ответах API, в логах ошибок, в алертах Slack в три часа ночи. Знание того, что означает каждый код, когда использовать тот или иной код в своих API и что типичные коды говорят об ошибке, делает вас значительно быстрее при отладке и помогает создавать более качественные сервисы.

Вы можете найти любой HTTP-код состояния с помощью справочника HTTP-кодов состояния BrowseryTools — бесплатно, без регистрации, всё работает в браузере.

Пять категорий

Коды состояния — трёхзначные числа. Первая цифра определяет категорию:

• 1xx — Информационные: запрос получен, обработка продолжается. Редко встречаются в большинстве приложений.
• 2xx — Успех: запрос получен, понят и принят.
• 3xx — Перенаправление: для завершения запроса требуется дополнительное действие. Клиент должен последовать редиректу.
• 4xx — Ошибка клиента: запрос некорректен или не авторизован. Ошибку допустил клиент.
• 5xx — Ошибка сервера: сервер не смог выполнить корректный запрос. Ошибку допустил сервер.

Это правило первой цифры важно: если вы видите незнакомый код (например, 429 или 451), вы по крайней мере знаете, на чьей стороне проблема — клиента или сервера — и завершился ли запрос успешно.

2xx: коды успеха

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

• 200 OK — универсальный успех. Тело ответа содержит запрошенные данные. Используется для GET-запросов и большинства ответов, возвращающих контент.
• 201 Created — создан новый ресурс. Должен включать заголовок Location, указывающий URL нового ресурса. Используйте для POST-запросов, создающих записи, а не 200.
• 204 No Content — запрос выполнен, но тело ответа отсутствует. Типично для DELETE-запросов и операций PATCH/PUT, когда клиенту не нужны обновлённые данные. Ответ не должен содержать тело.
• 206 Partial Content — используется с range-запросами (заголовок Range). Видеоплееры используют это для запроса конкретных байтовых диапазонов медиафайла без загрузки всего целиком.

# Паттерн проектирования REST API
POST   /api/users        → 201 Created  (тело: объект нового пользователя, Location: /api/users/123)
GET    /api/users/123    → 200 OK       (тело: объект пользователя)
PATCH  /api/users/123    → 200 OK       (тело: обновлённый пользователь) или 204 No Content
DELETE /api/users/123    → 204 No Content

3xx: коды перенаправления

Редиректы сообщают клиенту, что нужно обратиться по другому адресу. Заголовок Location содержит новый URL. Ключевое различие — между постоянными и временными редиректами, а также между теми, что сохраняют HTTP-метод, и теми, что его меняют.

• 301 Moved Permanently — ресурс постоянно перенесён по новому URL. Браузеры и поисковики кэшируют это. Браузер будет использовать GET для редиректа независимо от исходного метода (исторический курьёз). Используйте при постоянном переименовании URL или редиректе HTTP на HTTPS в устаревших конфигурациях.
• 302 Found — временный редирект. Как и 301, браузеры меняют POST на GET при редиректе (согласно спецификации, хотя спецификация была «неправильной» — см. 307). Используйте 302 только когда редирект действительно временный.
• 304 Not Modified — кэшированная версия актуальна; тело отсутствует. Сервер отправляет это в ответ на условный GET (с заголовком If-None-Match или If-Modified-Since). Браузер использует кэш. Важно для эффективности CDN и снижения нагрузки на полосу пропускания.
• 307 Temporary Redirect — как 302, но спецификация гарантирует сохранение исходного HTTP-метода. Если POST получает 307, браузер отправит POST на новый URL. Используйте 307 вместо 302 для временных редиректов с методами, отличными от GET.
• 308 Permanent Redirect — как 301, но также гарантирует сохранение метода. Современный стандарт для постоянных редиректов.

Распространённое заблуждение: 301 против 302 для SEO

Поисковые системы воспринимают 301 как сигнал передачи «ссылочного веса» (PageRank) со старого URL на новый и обновляют индекс. 302 говорит краулеру, что редирект временный, поэтому он продолжает индексировать исходный URL. Использование 302 там, где нужен 301, лишает редирект SEO-эффекта. Напротив, использование 301 для временного редиректа заставляет поисковики кэшировать редирект, что затрудняет его отмену.

4xx: коды ошибок клиента

Эти коды говорят о том, что клиент прислал неверный запрос. Не возвращайте 5xx для ошибок клиента — это вводит в заблуждение мониторинг и усложняет определение, что именно пошло не так: баг на сервере или некорректные входные данные от клиента.

• 400 Bad Request — запрос некорректен. Отсутствуют обязательные поля, невалидный JSON, неверные типы данных. Самый общий код 4xx; используйте более специфичные, когда возможно.
• 401 Unauthorized — несмотря на название, означает «не аутентифицирован». Клиент не предоставил учётные данные или они недействительны. Ответ должен включать заголовок WWW-Authenticate, указывающий способ аутентификации. Название — историческая ошибка; «не аутентифицирован» было бы точнее.
• 403 Forbidden — аутентифицирован, но не авторизован. Сервер знает, кто вы (или это не важно), и у вас нет прав. В отличие от 401, повторная аутентификация не поможет. Используйте 403, когда пользователь пытается получить доступ к ресурсу, который ему не разрешён.
• 404 Not Found — ресурса по этому URL не существует. Также возвращается, когда сервер хочет скрыть существование ресурса от неавторизованных пользователей (403 подтвердил бы существование ресурса; 404 скрывает этот факт).
• 409 Conflict — запрос конфликтует с текущим состоянием ресурса. Классический пример: попытка создать пользователя с уже существующим e-mail или обновить ресурс на основе устаревшей версии (конфликт оптимистичной блокировки).
• 422 Unprocessable Entity — запрос синтаксически корректен (валидный JSON, правильный Content-Type), но семантически недействителен (обязательное поле присутствует, но содержит недопустимое значение, нарушение бизнес-правила). Rails popularized использование 422 для ошибок валидации. Более специфичен, чем 400.
• 429 Too Many Requests — превышен лимит запросов. Должен включать заголовок Retry-After, сообщающий клиенту, сколько ждать. Необходим для любого публичного API.

401 против 403: важное различие

Одна из самых часто путаемых пар:

GET /api/admin/users
Authorization: (отсутствует)
→ 401 Unauthorized
   "Вы не сказали мне, кто вы. Войдите сначала."

GET /api/admin/users
Authorization: Bearer <действительный-токен-обычного-пользователя>
→ 403 Forbidden
   "Я знаю, кто вы. Вы не администратор. Доступ запрещён."

5xx: коды ошибок сервера

• 500 Internal Server Error — общий код для непредвиденных сбоев на стороне сервера. Необработанное исключение, нулевой указатель, запрос к базе данных, выбросивший ошибку. Не раскрывайте трассировки стека клиентам; записывайте их на сервере.
• 502 Bad Gateway — сервер, выступающий в роли прокси или шлюза, получил невалидный ответ от вышестоящего сервера. Типично, когда балансировщик нагрузки или обратный прокси не может достучаться до серверов приложений — приложение упало или не слушает нужный порт.
• 503 Service Unavailable — сервер временно не может обрабатывать запросы. Возможно, перегружен, находится в процессе деплоя или обслуживания. Должен включать заголовок Retry-After, если известна продолжительность простоя.
• 504 Gateway Timeout — прокси или шлюз не получил своевременного ответа от вышестоящего сервера. Вышестоящий сервер работает, но отвечает слишком медленно. Типичный симптом — слишком долгие запросы к базе данных или зависающие вызовы внешних API.

Коды состояния в проектировании REST API

Использование правильных кодов состояния делает ваш API самодокументируемым и простым для интеграции. Несколько рекомендаций:

• Никогда не возвращайте 200 с объектом ошибки в теле. Если запрос провалился, код состояния должен это отражать. Клиенты должны иметь возможность проверить только код состояния, чтобы понять, нужна ли обработка ошибки.
• Используйте 201 и заголовок Location при создании ресурсов через POST. Это позволяет клиентам обнаружить URL нового ресурса без разбора тела.
• Возвращайте 422 (а не 400) для ошибок валидации с структурированным телом ошибки, определяющим, какие поля не прошли проверку и почему.
• Используйте 409 для конфликтов, требующих разрешения на уровне приложения, а не просто для некорректных входных данных.
• Реализуйте 429 с ограничением частоты запросов с самого начала на любом публично доступном эндпоинте — добавить это задним числом значительно сложнее.

Отладка кодов состояния в DevTools

Откройте вкладку Network в DevTools браузера и ищите запросы, выделенные красным — это ответы 4xx или 5xx. Кликните на запрос, чтобы увидеть точный код состояния, заголовки ответа (полезны для WWW-Authenticate, Location, Retry-After) и тело ответа (которое часто содержит сообщение об ошибке от сервера). Для редиректов включите «Preserve log», чтобы панель DevTools не очищалась при навигации — иначе вы пропустите цепочку редиректов.

Если вы встретили незнакомый код состояния, справочник HTTP-кодов состояния BrowseryTools даёт вам официальное описание, RFC-источник и заметки о типичном использовании — без необходимости покидать вкладку браузера.