Коды статуса HTTP Когда возвращать 404 вместо 410 вместо 301 (и прекратить догадываться)

Вы вернули 200 с {"error": "user not found"} в теле. Ваши 301-сигналы на самом деле — 302. Удалённые ресурсы продолжают возвращать 404 вечно. Давайте рассмотрим наиболее часто ошибаемые разработчиками коды состояния и то, что следует возвращать вместо этого.

4xx против 5xx: Не один и тот же бакет

Наиболее фундаментальное разделение в кодах состояния HTTP: 4xx — вина клиента, 5xx — ваша вина. Просто в теории, нарушается постоянно на практике.

Наиболее распространённая ошибка: возвращение 500 при ошибке валидации. Пользователь отправил некорректный JSON в вашу API. Это — 400 Ошибка запроса — его заголовок был неправильным. Код 500 говорит клиенту: «мы упал», что вызывает оповещения, записывается как ошибка сервера и заставляет автоматические системы повторять попытки (что усугубляет плохой день). Если клиент отправил бессмысленные данные, скажите об этом с помощью 4xx.

404 против 410: Проблема удалённого ресурса

404 Не найдено означает: «я не имею этого сейчас, но возможно, попробуйте позже». Роботы-поисковики — включая Googlebot — рассматривают 404 как временный. Они будут постоянно перепроверять его.

410 Удалено означает: «этот ресурс был полностью удалён. Прекратите спрашивать». Googlebot удаляет URL с 410 из индекса быстрее, чем с 404, и останавливается от поиска этих URL раньше. Это важно для SEO и для расхода поискового бюджета на больших сайтах.

Практическое правило: если ваша API удаляет запись и она больше не возвращается, возвращайте 410 при последующих запросах. Единственная причина для предпочтения 404 в случае удалённого ресурса — если он может быть восстановлен — мягкая удалённость с временным окном восстановления, опубликованная статья, которая может быть перепубликована и т.д. В противном случае 410 более честный и поисковые системы будут вам благодарны.

301 против 302 (и почему существуют 307/308)

301 Перенесено постоянно: Эта URL ушла навсегда, используйте новую. Браузеры активно кэшируют 301. Поисковые системы передают ссылочную ценность на новую страницу. Если вы объединяете домены или переносите сайт навсегда, 301 — то, что вам нужно.

302 Найдено: Перейдите на эту другую URL на время, но вернитесь к оригиналу позже. Нет кэширования. Нет передачи ссылочной ценности. Используйте это для перенаправлений при входе, временных страниц обслуживания или тестов A/B.

Режим сбоя: использование 302 для постоянных перемещений. Вы думаете: «одно и то же, просто другое», но поисковые системы не передают ссылочную ценность через 302. Годы SEO-работы остаются привязанными к старому URL, в то время как новый не получает рейтинга. Если вы перенесли что-то навсегда, используйте 301.

Затем есть 307 Временное перенаправление и 308 Постоянное перенаправление. Эти варианты безопасны относительно метода: при переходе по 301/302 браузер может снизить POST до GET, в то время как 307/308 сохраняют исходный HTTP-метод. Если вы перенаправляете API-конечные точки, принимающие тела POST, 307 (временное) или 308 (постоянное) сохраняют метод.

Код	Тип	Кэширование?	Сохраняет метод?	Используется для
301	Постоянное	Да	Нет (может снизиться до GET)	Постоянные перемещения сайта, объединение URL
302	Временное	Нет	Нет (может снизиться до GET)	Перенаправления при входе, временная недоступность
307	Временное	Нет	Да	Временное перенаправление для API-конечных точек с методом POST
308	Постоянное	Да	Да	Постоянное перенаправление для API-конечных точек с методом POST

401 против 403: аутентификация против авторизации

Название вызывает путаницу. 401 Недоступно на самом деле означает неавторизовано — вы не вошли в систему, или у вас отсутствуют или недействительные данные аутентификации. 403 Запрещено означает, что вы авторизованы, но у вас нет разрешения на доступ к этому ресурсу.

Практическое различие: 401 должен запрашивать экран входа или обновление токена. 403 должен показывать сообщение «доступ запрещён». Возврат неправильного кода означает, что клиент не знает, должен ли он запрашивать данные аутентификации или отказаться.

Есть и безопасностная сторона. Некоторые API возвращают 404 вместо 403 для ресурсов, которые не могут быть доступны пользователем, чтобы избежать утечки того, что ресурс существует. Если вы возвращаете 403 на ресурс из другого тенанта, вы подтверждаете его существование. Возврат 404 более безопасен с точки зрения информации, хотя это усложняет отладку для законных пользователей. Выберите подход, соответствующий вашей модели угроз и примените его последовательно.

429: Ограничение скорости, с заголовком, который действительно помогает

Простое 429 Слишком много запросов неприятно. 429 с заголовком Retry-After на самом деле полезен.

HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1746374400

Retry-After может быть числом секунд или HTTP-датой. Хорошие клиенты автоматически отступят. Без него вы возвращаете код ошибки и надеетесь, что клиент понимает, когда перезапускать — большинство из них просто продолжат нажимать на вашу конечную точку, что уничтожает цель ограничения скорости.

Не возвращайте 503 при ограничении скорости. 503 означает «сервис недоступен» — сбой инфраструктуры, развертывание в процессе, отключённый кирпич. Ограничение скорости — это политическая мера, а не сбой сервиса. 429 существует именно для этого.

«200 с телом ошибки» — антимодель

Это появляется в производственных API и нужно остановить:

HTTP/1.1 200 OK
Content-Type: application/json

{"status": "error", "message": "user not found"}

Это нарушает всё, что зависит от семантики HTTP. Инструменты мониторинга отмечают запрос как успешный. Балансировщики нагрузки передают его. Клиентские библиотеки не бросают исключения. Логи выглядят чистыми, хотя пользователи видят ошибки. Решение — однострочное: возвращайте правильный код состояния. 200 означает, что всё прошло успешно. Если это не прошло, не возвращайте 200.

То же правило применимо к 201 и 200 при создании ресурсов. Если POST к /users создаёт нового пользователя, возвращайте 201 Создано с Location заголовок, указывающий на новый ресурс. Возвращайте 200, и вы теряете информацию, которую клиенты могут использовать, чтобы избежать дополнительного круга запросов.

Сценарий API → Правильный код состояния

Вот справочная таблица для наиболее часто встречающихся сценариев в разработке REST API:

Сценарий	Код состояния	Примечания
Тело запроса имеет некорректный JSON	400 Ошибка запроса	Включите сообщение, указывающее на ошибку парсинга
Отсутствует или неверное поле в запросе	422 Невозможно обработать сущность	422 более точен, чем 400, для ошибок валидации семантического уровня
Токен аутентификации отсутствует или истёк	401 Недоступно	Включить WWW-Authenticate заголовок
Авторизован, но нет разрешений	403 Запрещено	Или 404, если скрытие существования ресурса является требованием
Ресурс не найден, может быть возвращён	404 Не найдено	Для временного отсутствия или неизвестных ресурсов
Ресурс был полностью удалён	410 Удалено	Поисковые роботы остановятся на более раннем этапе повторной проверки
Создан новый ресурс	201 Создано	Добавить Location: /resources/new-id заголовок
DELETE успешно завершён, тело пустое	204 Без содержимого	Не возвращайте пустой JSON-объект с 200
Постоянное изменение URL	301 Перенесено постоянно	Поисковые системы передают ссылочную ценность
Временное перенаправление	302 Найдено	Нет кэширования, нет передачи ценности
Превышено ограничение скорости	429 Слишком много запросов	Всегда включайте Retry-After
Неожиданная ошибка сервера	500 Внутренняя ошибка сервера	Не утечка стековых трасс в теле
Верхний уровень зависит	503 Сервис недоступен	Добавить Retry-After если время отсутствия ограничено
Перенаправление после POST, сохранение метода	307 или 308	307 временно, 308 постоянно

Когда вы находитесь в процессе PR и хотите проверить, что означает код состояния, вы можете использовать Инструмент поиска кодов состояния HTTP для получения определения по спецификации, типичных случаев использования и того, какой RFC определяет его.

Проверка цепочек перенаправлений

После миграции сайта или перестройки URL важно проверить полную цепочку перенаправлений — особенно если у вас есть 301-перенаправления, которые позже были изменены на другие адреса, создавая многоступенчатые цепочки, которые утечивают ссылочную ценность. Инструмент Проверка перенаправлений отслеживает цепочку и показывает каждый код состояния последовательно, чтобы вы могли убедиться, что всё разрешается за один шаг.

Вам также может понравиться