HTTP-методы и коды ответов, которые нужно знать разработчику

Главное в двух фразах

HTTP-метод описывает намерение клиента: прочитать, создать, изменить или удалить. Код ответа сообщает результат. Если оба выбраны правильно, клиент, прокси, кэш и мониторинг понимают происходящее без чтения тела ответа.

Пять основных методов

• Безопасный метод ничего не меняет на сервере. GET нельзя использовать для удаления или изменения данных: поисковые роботы и браузеры могут вызывать его сами.
• PUT требует передать ресурс полностью. Поля, которые вы не прислали, считаются удалёнными или сброшенными.
• PATCH передаёт только изменения, например новую цену товара.

Идемпотентность простыми словами

Метод идемпотентен, если повторный одинаковый запрос даёт тот же итоговый результат, что и первый.

• DELETE /orders/7 два раза — заказ удалён, состояние то же.
• PUT /products/42 с одинаковым телом дважды — товар в том же состоянии.
• POST /orders два раза — два заказа.

Это важно при сбоях сети: если ответ не пришёл, идемпотентный запрос можно безопасно повторить. Для POST повтор опасен — например, двойное списание денег. Решение — ключ идемпотентности: клиент отправляет уникальный заголовок, и сервер не выполняет одну и ту же операцию дважды.

Коды 2xx: успех

• 200 OK — запрос выполнен, в теле есть данные.
• 201 Created — ресурс создан. Хорошая практика — вернуть его и заголовок Location с адресом.
• 202 Accepted — запрос принят, обработка будет позже (например, генерация отчёта).
• 204 No Content — успешно, тела нет. Часто для DELETE.

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

• 301 Moved Permanently — адрес изменился навсегда. Важно для SEO при переезде страниц.
• 302 Found — временное перенаправление.
• 304 Not Modified — у клиента актуальная копия из кэша, данные повторно не передаются.
• 307 / 308 — временное и постоянное перенаправление с сохранением метода и тела запроса.

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

• 400 Bad Request — некорректный запрос: битый JSON, неверный формат.
• 401 Unauthorized — клиент не аутентифицирован: нет токена или он истёк.
• 403 Forbidden — клиент известен, но прав не хватает.
• 404 Not Found — ресурса нет.
• 405 Method Not Allowed — метод не поддерживается для этого адреса.
• 409 Conflict — конфликт состояния: такой email уже занят, версия устарела.
• 422 Unprocessable Content — синтаксис верный, но данные не прошли валидацию.
• 429 Too Many Requests — превышен лимит запросов.

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

• 500 Internal Server Error — непредвиденная ошибка в коде.
• 502 Bad Gateway — прокси получил некорректный ответ от вышестоящего сервера.
• 503 Service Unavailable — сервис временно недоступен: перегрузка или обслуживание.
• 504 Gateway Timeout — вышестоящий сервер не ответил вовремя.

Правило: если клиент может исправить запрос сам — это 4xx. Если виноват сервер — 5xx. Мониторинг обычно поднимает тревогу именно на рост 5xx.

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

• Возвращать 200 с "error": true в теле. Клиенты, кэши и мониторинг считают запрос успешным.
• Путать 401 и 403. 401 — «кто вы?», 403 — «знаем, кто вы, но нельзя».
• Отдавать 500 на неверные данные. Ошибка валидации — это 400 или 422, а не сбой сервера.
• Менять данные через GET. Ссылка вида /delete?id=5 может сработать от предзагрузки браузера.