Статус-коды, которые реально важны в проде

Платёжный шлюз начал падать на апстриме во время пятничного деплоя. Все дашборды оставались зелёными: success rate 100%, error rate 0%, ни одного алерта. Дежурный инженер узнал об инциденте из твитов клиентов, а не из мониторинга. Причина — одна строка: шлюз ловил падения апстрима и возвращал 200 OK с { "error": "upstream timeout" } в теле. Метрики считали HTTP-статус, поэтому полный отказ сорок минут выглядел как идеальное здоровье.

Классы — это решение о маршрутизации, а не зубрёжка

Запомнить, что 404 — это «не найдено», уровень джуна. Взгляд сеньора: первая цифра — это инструкция маршрутизации для машин, которые никогда не читают тело ответа: кэш, балансировщик, APM-агент, цикл ретраев клиента. Они ветвятся по классу, и ветвятся сразу.

• 2xx — сработало; ответ кэшируем по своим заголовкам, считай успехом.
• 3xx — иди в другое место; следуй Location или используй кэш.
• 4xx — ты, клиент, прислал что-то не то; не ретрай тот же запрос, он упадёт точно так же.
• 5xx — я, сервер, упал; запрос мог быть валидным, поэтому ретрай может сработать.

Раздел 4xx/5xx — несущий. Это разница между «стоп, ты сломал» и «подожди, я сломал, попробуй снова». Ошибись классом — и каждая машина ниже по потоку примет неверное решение: кэш сохранит отказ, цикл ретраев будет долбить запрос, который никогда не пройдёт, дашборд просчитается с инцидентом.

2xx — не одно и то же: 200 vs 201 vs 202 vs 204

Класс успеха несёт реальную информацию, которой сеньор формирует контракт API.

• 200 OK — готово, вот результат. Синхронно, полностью.
• 201 Created — теперь существует ресурс; верни заголовок Location с указанием на него. Это правильный ответ на успешный POST /orders, а не голый 200.
• 202 Accepted — «я принял твой запрос, но он ещё не выполнен». Работа в очереди или асинхронна. Тело должно вернуть способ опросить статус. Вернуть тут 200 — ложь: клиент думает, что заказ ушёл, а он ещё лежит в очереди.
• 204 No Content — успех, и сознательно нечего возвращать (DELETE или PUT, который не изменил ничего, что клиенту надо отразить). Экономит раунд-трип на парсинг пустого тела.

Различие 202-vs-200 — там, где текут асинхронные системы. Если эндпоинт ставит работу в Kafka и возвращается сразу, 202 говорит клиенту «опрашивай меня». 200 говорит «мы закончили» — и теперь его UI показывает подтверждённый заказ, которого ещё нигде нет.

Словарь 4xx: 400 vs 422 vs 409 vs 412 и 401 vs 403

Здесь большинство API неряшливы — и здесь точный клиент может дать полезное сообщение об ошибке вместо общего «что-то пошло не так».

RFC 9110 проводит 400 как синтаксис, а 422 как семантику: 400 — «я не смог это распарсить», 422 — «я распарсил, и значения неверны». Граница размытая, и многие API сваливают оба в 400, но различие стоит держать — оно говорит клиенту, чинить форму или данные, а это разница между ошибкой разработчика и ошибкой пользователя.

Пару 401 vs 403 постоянно путают. 401 значит «я не знаю, кто ты» — фикс в аутентификации. 403 значит «я точно знаю, кто ты, и тебе всё равно нельзя» — обновление токена не поможет. Вернуть 401 на отказ авторизации загоняет клиентов в бессмысленный цикл релогина.

5xx: чья вина и что клиент делает дальше

Класс 5xx — там, где живёт стратегия ретраев, а под-коды распределяют вину.

• 500 Internal Server Error — твоё приложение бросило исключение и не обработало. Баг в твоём коде.
• 502 Bad Gateway — прокси/балансировщик получил малформед или ничего от апстрима, который вызвал. Сам шлюз цел; что-то за ним сломано.
• 503 Service Unavailable — сервер сознательно не обслуживает: перегружен, дренится, на обслуживании. Это единственный 5xx, который должен нести заголовок Retry-After.
• 504 Gateway Timeout — шлюз ждал апстрим и сдался. Запрос мог завершиться на бэкенде, хотя клиент увидел таймаут, — именно поэтому слепой ретрай неидемпотентного вызова тут опасен.

Рефлекс сеньора: 5xx ретраебельно (запрос мог быть валидным, а сбой временным), 4xx нет (запрос неверен и упадёт точно так же) — с 429 как явным ретраебельным исключением в диапазоне 4xx.

429 и Retry-After: бэкофф, которым управляет сервер

429 Too Many Requests говорит, что ты упёрся в rate limit. Правильный ответ несёт заголовок Retry-After — либо число секунд (Retry-After: 30), либо HTTP-дату. Сервер знает своё окно лимита; уважай его. Откатывайся к клиентскому экспоненциальному бэкоффу с джиттером (1с, 2с, 4с, 8с…) только когда Retry-After нет. Google Cloud Storage, OpenAI и Stripe документируют ровно этот порядок: сначала читай Retry-After, потом бэкофф с джиттером.

Правило ретраев, которое всё связывает — и которое вызывает реальные инциденты при нарушении: ретрай 5xx и 429; никогда слепо не ретрай неидемпотентный 4xx или неидемпотентный запрос после таймаута. GET, PUT, DELETE идемпотентны — ретрай безопасен. POST — нет. Если POST /charge ловит таймаут (504) и клиент ретраит, списание может пройти дважды. Фикс — ключ идемпотентности: Stripe и Square требуют от клиентов слать уникальный ключ на логическую операцию, чтобы сервер дедуплицировал ретраи вместо двойного списания.