Справочник HTTP: коды ответов, методы, заголовки, MIME

Коды ответов HTTP с советами, когда их применять и можно ли повторять запрос, методы с идемпотентностью, заголовки и MIME-типы с поиском.

Данные обрабатываются в браузере и никуда не отправляются

Раздел

Класс кодов

Ввод

Результат

Здесь появится результат

Введите данные слева - результат появится сразу

Как пользоваться

Выберите раздел и введите слово для поиска - таблица фильтруется сразу. «Коды ответов» объясняют, что значит каждый код, когда его применять в API и можно ли безопасно повторить запрос (колонка «Повтор»); их можно отфильтровать по классу 1xx-5xx. «Методы» показывают безопасность, идемпотентность, кэширование и применимость тела запроса. «Заголовки» содержат частые заголовки запроса и ответа с примерами значений, а «MIME-типы» - форматы для Content-Type.

Это справочник для проектирования API и разбора интеграций: ищите по номеру (404), по названию (Conflict), по слову из описания (кэш, redirect, авторизация, json) или по имени заголовка (Retry-After). Для разбора реального запроса или ответа используйте «Разбор HTTP-запроса» на этом сайте.

Частые ошибки

Вот ошибки в использовании кодов и методов HTTP, которые встречаются чаще всего:

200 OK с ошибкой в теле

Ответ 200 с {"success": false} ломает мониторинг, кэши и повторные запросы: все они ориентируются на код. Ошибки возвращайте кодами 4xx и 5xx, а детали - в теле (формат problem+json).

401 вместо 403 и наоборот

401 значит «вы не аутентифицированы» (нет или недействительный токен), 403 - «вы известны, но прав нет». Путаница мешает клиенту решить, обновить токен или показать «доступ запрещён».

404 для пустого результата

Пустой список по поиску - это 200 с пустым массивом. 404 означает, что нет самого ресурса по адресу. Иначе клиенты не отличат «ничего не найдено» от неверного адреса.

500 для ошибок клиента

Если клиент прислал некорректные данные, это 400 или 422, а не 500. Код 500 должен означать ошибку сервера - на нём срабатывают оповещения и автоматические повторы.

POST для всего подряд

Использование POST для чтения и изменения лишает запросы кэша и идемпотентности. Читайте через GET, заменяйте через PUT, удаляйте через DELETE, а для безопасных повторов POST добавляйте ключ идемпотентности.

Перенаправление, меняющее метод

301 и 302 исторически превращают POST в GET. Если метод и тело должны сохраниться, используйте 308 и 307; если после POST нужно показать страницу результата - 303.

Частые вопросы

Это справочник по русскоязычным описаниям - можно ли доверять?

Описания сверены со стандартами RFC 9110 и RFC 9457. В колонках «Когда применять» собраны практические рекомендации по проектированию API, их стоит воспринимать как ориентир: в вашем проекте могут быть свои соглашения.

В чём разница между 401 и 403?

401 Unauthorized - клиент не аутентифицирован: не передал учётные данные или токен недействителен. Ответ должен содержать WWW-Authenticate. 403 Forbidden - сервер знает, кто вы, но доступ к ресурсу запрещён. Повторять запрос с теми же данными бессмысленно.

Чем отличаются 301, 302, 303, 307 и 308?

301 и 308 - постоянный переезд, 302 и 307 - временный. Разница между парами в методе: 301 и 302 позволяют клиенту сменить POST на GET, а 308 и 307 требуют сохранить метод и тело. 303 всегда требует перейти методом GET, обычно после POST.

400 или 422 для ошибок валидации?

400 подходит для запросов, которые не удалось разобрать (битый JSON, неверная структура), а 422 - для синтаксически верных запросов, нарушающих правила данных (дата в прошлом, неверный email). Многие API используют 400 для обоих случаев - главное придерживаться единого правила.

Что такое идемпотентность и почему она важна?

Метод идемпотентен, если повтор того же запроса даёт то же состояние, что и одно выполнение: GET, PUT, DELETE. Это позволяет безопасно повторять запросы после таймаута. POST не идемпотентен - для него используют заголовок Idempotency-Key.

Когда безопасно повторять запрос?

Идемпотентные запросы (GET, PUT, DELETE) можно повторять при 408, 429, 502, 503, 504 с задержкой и случайным разбросом (jitter), учитывая Retry-After. Неидемпотентные (POST, PATCH) - только с ключом идемпотентности, иначе возможен дубль операции.

В чём разница между 502, 503 и 504?

502 Bad Gateway - шлюз получил некорректный ответ от приложения. 503 Service Unavailable - сервис временно недоступен (перегрузка, обслуживание), часто с Retry-After. 504 Gateway Timeout - приложение не ответило вовремя; здесь операция могла выполниться.

Чем PUT отличается от PATCH и POST?

PUT заменяет ресурс целиком и идемпотентен, PATCH изменяет часть полей (идемпотентность зависит от формата патча), POST создаёт ресурс по адресу коллекции или запускает действие и не идемпотентен.

Что такое preflight-запрос CORS?

Перед «непростым» кросс-доменным запросом (например, с заголовком Authorization или методом PUT) браузер отправляет OPTIONS с заголовками Origin, Access-Control-Request-Method и Access-Control-Request-Headers. Сервер должен ответить Access-Control-Allow-Origin, -Methods и -Headers, иначе браузер заблокирует основной запрос.

Курс «Проектирование API и интеграций»

Глубокое погружение в REST, gRPC, SOAP, проектирование баз данных и брокеры сообщений (Kafka, RabbitMQ). Делегирование рутины нейросетям (ИИ). Перестанете бояться технических собеседований и начнете говорить с разработчиками на одном языке. Курс собран так, чтобы пробить зарплатный потолок и вырасти в грейде - ученики тому подтверждение.