Справочник 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.

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

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

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

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

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; 307 и 308 сохраняют метод. 303 направляет клиента к другому ресурсу для получения представления с помощью GET или HEAD.

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

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

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

Идемпотентность означает одинаковый предполагаемый эффект одного и нескольких одинаковых запросов, а не одинаковые ответы. Это свойство GET, HEAD, PUT, DELETE, OPTIONS и TRACE. Для POST и PATCH оно зависит от конкретной операции; один заголовок Idempotency-Key без серверной поддержки его не обеспечивает.

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

Повторяйте запрос только когда известна его безопасность и ошибка временная. Используйте ограничение попыток, задержку с jitter и учитывайте Retry-After. Для операции с побочным эффектом нужен идемпотентный контракт или серверная дедупликация; просто добавить новый Idempotency-Key недостаточно. Один и тот же ключ используют для повторов одной операции.

В чём разница между 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, GraphQL и JSON-RPC, архитектурные подходы, SQL и NoSQL, брокеры сообщений и работа с ИИ. Программа курса помогает систематизировать знания об API и интеграциях; содержание и условия обучения смотрите на Stepik.

Перейти к курсу на Stepik