HTTP-коды состояния - это трёхзначные числа в начале каждого ответа сервера, которые коротко говорят, что произошло. По ним браузеры, клиенты, прокси и CDN решают, кэшировать ли ответ, перенаправлять ли запрос, повторять ли его и показывать ли пользователю ошибку.
Каждый код относится к одному из пяти классов - по первой цифре: 1xx - информационные, 2xx - успех, 3xx - перенаправление, 4xx - ошибка клиента, 5xx - ошибка сервера. Зная класс, общий смысл кода обычно понимаешь ещё до того, как лезешь в справочник.
На практике большинство приложений обходится небольшим набором: 200, 201, 204, 301, 302, 304, 400, 401, 403, 404, 409, 422, 429, 500, 502, 503. Понимать, что *означает* каждый - и в чём разница между 401 Unauthorized и 403 Forbidden или между 301 Moved Permanently и 302 Found - как раз то, что отличает крепкого backend- или API-разработчика.
Что вы узнаете, пользуясь этим справочником
Первая цифра всегда говорит о классе: 1xx - информация, 2xx - успех, 3xx - редирект, 4xx - ошибка клиента, 5xx - ошибка сервера.
Коды состояния - это *часть контракта* API. Клиенты должны ветвить логику по коду, а не парсить текст ошибки из тела ответа.
4xx означает, что клиент сделал что-то не так (плохой ввод, нет авторизации, нет ресурса). 5xx - что сервер упал независимо от того, что прислал клиент.
Как пользоваться справочником шаг за шагом
1
Ищите по коду или названию
Введите число (404, 429) или ключевое слово (auth, redirect, rate limit) - список кодов отфильтруется на лету.
2
Фильтруйте по классу
Чипы классов (1xx, 2xx, 3xx, 4xx, 5xx) помогают сузить список, когда вы скорее изучаете тему, чем ищете конкретный код.
3
Читайте объяснение по-человечески
В каждой записи указано, когда код отправляется, как обычно реагирует клиент и какая причина встречается чаще всего.
4
Сравнивайте близкие коды
Используйте перекрёстные ссылки между путаными парами (401 vs 403, 301 vs 302), чтобы выбрать правильный код для своего API.
Успех, но без тела. Часто используется после DELETE или PUT, когда возвращать нечего.
Все три - коды успеха, разница только в том, что несёт ответ. 201 должен возвращать заголовок Location со ссылкой на созданный ресурс; 204 по определению пустой.
Временный редирект. Браузеры каждый раз заново обращаются к исходному URL, закладки остаются на нём же.
301 уместен, когда ресурс действительно переехал (ребрендинг, переработка URL-структуры). 302 - для краткосрочных редиректов: A/B-тесты, перенаправления при логине, страница «на техобслуживании».
Сервер знает, кто вы, но прав на этот ресурс у вас нет.
Если с другими учётными данными запрос мог бы сработать - возвращайте 401. Если никакие данные не помогут (ресурс просто закрыт для этого пользователя) - возвращайте 403.
Gateway timeout - прокси достучался до апстрима, но не получил ответ вовремя.
Все четыре - ошибки сервера, но рассказывают разные истории при отладке. 500 - это ваш код; 502 и 504 намекают на проблемы в сети между сервисами; 503 - про нехватку ресурсов.
Типичные ошибки при работе с HTTP-кодами
Отдавать 200 OK с телом {"error": "..."}. Код состояния - часть контракта: используйте подходящий (400, 404, 500), чтобы клиенты могли ветвить логику именно по нему.
Использовать 401 для ошибок прав доступа. 401 - это про аутентификацию, а отказ в правах - это 403.
Возвращать 200 для только что созданных ресурсов вместо 201 с заголовком Location.
FAQ по HTTP-кодам состояния
Что означает HTTP 404?
404 Not Found означает, что сервер понял запрос, но ресурса по этому URL не существует. Чаще всего путь указан неверно, ресурс удалён или URL содержит опечатку.
Чем отличаются 401 и 403?
401 Unauthorized - вы не аутентифицированы, сервер не знает, кто вы. 403 Forbidden - вы аутентифицированы, но прав на этот ресурс у вас нет. Другие учётные данные могут починить 401, но не 403.
Чем отличаются 301 и 302?
301 Moved Permanently - постоянный редирект, браузеры и поисковики обновляют свои записи. 302 Found - временный, клиенты продолжают ходить по исходному URL. 301 - для постоянных переездов, 302 - для временных обходных путей.
Что означает HTTP 500?
500 Internal Server Error - общая ошибка на стороне сервера, обычно происходит, когда наверх всплывает необработанное исключение. Клиент тут ни при чём - сервер не справился с корректным запросом.
Нужно ли всегда возвращать конкретный код?
Да. Универсальный 200 OK на ошибки или 500 на всё подряд делают API неудобным. Выбирайте наиболее точный подходящий код - клиенты, прокси, мониторинг и логика повторов смотрят именно на него.
Что означает HTTP 429?
429 Too Many Requests отдаётся, когда клиент упёрся в rate limit. В ответе стоит указывать заголовок Retry-After, чтобы клиент знал, когда можно повторить запрос.
