Коды состояния HTTP

Пять классов кодов состояния

Клиент, получивший незнакомый код, обрабатывает его как код x00 того же класса: неизвестный 499 — как 400, неизвестный 299 — как 200. Поэтому новые коды можно вводить, не ломая старое ПО.

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

Промежуточные ответы перед окончательным: 100 Continue, 101 Switching Protocols для WebSocket, 103 Early Hints для предзагрузки.

2xx Успех

Запрос выполнен. 200 OK — вариант по умолчанию; 201 Created и 204 No Content точнее сообщают, что произошло.

3xx Перенаправление

Клиент должен искать в другом месте, обычно по URL из заголовка Location, — или, в случае 304 Not Modified, использовать копию из кеша.

4xx Ошибка клиента

Запрос неверен: искажён, не аутентифицирован, запрещён, обращён к несуществующему ресурсу или слишком част. Повтор без изменений не поможет.

5xx Ошибка сервера

Запрос мог быть корректным, но сбой произошёл на сервере или за ним. Такие ошибки часто временные, и их стоит повторять с нарастающей паузой (back-off).

Как выбрать правильный код для API

Большинству API хватает десятка кодов. Для успеха: 200 с телом ответа, 201 с заголовком Location, когда что-то создано, 202, когда обработка произойдёт позже, и 204, когда возвращать нечего. Для ошибок клиента: 400 для искажённых запросов, 422 для корректно оформленных данных, не прошедших валидацию, 401, когда учётные данные отсутствуют или недействительны, 403, когда они действительны, но недостаточны, 404 для неизвестных ресурсов, 409 для конфликтов вроде повторного email и 429 для ограничения частоты запросов. Для ошибок сервера: 500 для багов, а 502, 503 и 504 — для сбоев промежуточной инфраструктуры.

Какой бы ни был код, возвращайте тело с пояснением. RFC 9457 «Problem Details» (application/problem+json) задаёт для него стандартную структуру с полями type, title, status и detail. Никогда не возвращайте 200 с ошибкой внутри тела: кеши, мониторинг и логика повторов читают код состояния, а не ваш JSON. Чтобы отформатировать такое тело, используйте форматировщик JSON.

Коды, которые часто путают

401 vs 403

401 Unauthorized означает «я не знаю, кто вы»: войдите или отправьте действительный токен. 403 Forbidden означает «я знаю, кто вы, и вам это делать нельзя».

301 vs 302 vs 307 vs 308

301 и 308 — постоянные и передают поисковый вес новому URL; 302 и 307 — временные. 307 и 308 гарантируют сохранение метода и тела запроса, а при 301 и 302 браузеры превращают POST в GET.

400 vs 422

400 — для запросов, которые сервер вообще не может разобрать; 422 — для корректного JSON, содержимое которого нарушает правила, например нет обязательного поля.

404 vs 410

404 говорит, что здесь сейчас ничего нет; 410 — что здесь что-то было и было удалено намеренно, поэтому поисковики убирают страницу быстрее.

502 vs 504

Оба приходят от прокси или балансировщика нагрузки. 502 означает, что вышестоящий сервер ответил некорректно или закрыл соединение; 504 — что он не ответил вовремя.

500 vs 503

500 — непредвиденный сбой, обычно баг. 503 — известное временное состояние (обслуживание или перегрузка), и к нему стоит добавлять Retry-After.

Коды состояния и SEO

Поисковые системы внимательно читают коды состояния. Используйте 301 или 308, когда страница переезжает навсегда, чтобы её позиции переехали вместе с ней; 302 сообщает, что индексировать нужно по-прежнему старый URL. Для отсутствующих страниц отдавайте настоящий 404 или 410 — страница «не найдено» с кодом 200 считается «soft 404» и тратит краулинговый бюджет. Во время обслуживания возвращайте 503 с Retry-After, чтобы страницы не выпали из индекса. Что могут обходить роботы, задайте в генераторе robots.txt.

Ответы с кодами 200, 203, 204, 206, 300, 301, 308, 404, 405, 410, 414, 451 и 501 могут кешироваться браузерами и CDN даже без явных заголовков свежести, поэтому случайный 404 или 301 может надолго задержаться; задавайте для них Cache-Control осознанно.

Неофициальные коды, которые встречаются в логах

Некоторых кодов нет в реестре IANA, но на практике они распространены. nginx пишет в лог 499, когда клиент обрывает соединение до ответа, и 444, когда сам закрыл соединение без ответа. Cloudflare возвращает 520–526, когда не может получить нормальный ответ от исходного сервера: 521 — источник отклонил соединение, 522 — истёк тайм-аут, 524 — ответ занял больше 100 секунд, 525/526 — не удалось установить TLS с источником. Laravel отправляет 419, когда истёк срок CSRF-токена. В списке эти коды помечены как «неофициальные», и их можно скрыть.