Коды ответа HTTP

Код ответа — первое, что сообщает сервер: получилось или нет, и если нет, то по чьей вине. Первая цифра задаёт класс, остальные уточняют. Клиент, который не знает конкретный код, обязан обработать его как общий код своего класса: неизвестный 299 как 200, неизвестный 499 как 400.

1xx: информационные

2xx: успех

3xx: перенаправления

Как выбрать:

• Сайт переехал на новый адрес навсегда, только GET-страницы — 301. Поисковики переносят вес на новый адрес.
• То же, но через адрес идут и POST-запросы API — 308, чтобы метод и тело не потерялись.
• После отправки формы перенаправить на страницу результата — 303. Это классический шаблон «POST, перенаправление, GET»: обновление страницы не отправит форму второй раз.
• Временное перенаправление, например на страницу входа, — 302 или 307, если важно сохранить метод.

304 Not Modified — не перенаправление в обычном смысле. Клиент спросил «изменился ли ресурс с прошлого раза» через заголовки If-None-Match или If-Modified-Since, а сервер ответил «нет, берите из кеша» без тела. Подробнее о заголовках кеша в соседней статье.

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

401 или 403

Самая частая путаница. Название 401 сложилось исторически и вводит в заблуждение: на деле это «мы не знаем, кто вы». Вместе с ним сервер должен прислать заголовок WWW-Authenticate со способом входа. 403 значит «мы знаем, кто вы, но вам сюда нельзя», и повторная попытка с тем же пользователем не поможет.

400 или 422

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

{
  "error": "validation_failed",
  "message": "Проверьте поля формы",
  "fields": {
    "email": "Такой адрес уже зарегистрирован",
    "age": "Должно быть число от 14 до 120"
  }
}

Для таких тел есть стандартный формат RFC 9457, «Problem Details»: поля type, title, status, detail, instance и тип содержимого application/problem+json.

404 вместо 403

Иногда сервер отвечает 404 на чужой ресурс, к которому нет доступа. Так не раскрывается сам факт, что ресурс с таким идентификатором существует. Например, на запрос чужого закрытого репозитория хостинги обычно отвечают именно 404.

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

Как разбирать 502 и 504

Оба кода выдаёт не само приложение, а то, что стоит перед ним: nginx, балансировщик, облачный шлюз.

• 502 чаще всего значит, что приложение не запущено, упало во время запроса или слушает не тот порт или сокет. Смотрите журнал ошибок nginx (/var/log/nginx/error.log), там будет connect() failed или upstream prematurely closed connection.
• 504 значит, что приложение живо, но отвечает дольше таймаута. Причина обычно в медленном запросе к базе или во внешнем вызове. Увеличение таймаута помогает только как временная мера.

Какой код вернуть: короткая памятка для API

Как посмотреть код ответа

curl -I localhost:8080/health                      # только заголовки
curl -s -o /dev/null -w '%{http_code}\n' localhost:8080/api/users
curl -sL -o /dev/null -w '%{http_code} %{url_effective}\n' localhost:8080/old

Последняя команда проходит по всем перенаправлениям и показывает итоговый код и адрес. Больше приёмов в шпаргалке по curl. В браузере код виден во вкладке «Сеть» инструментов разработчика.