API
Статус-коды: тест с выбором ответа
Суть Синтез по юниту статус-кодов в формате выбора: подобрать верный код под сценарий, разделить ответственность 4xx/5xx, Retry-After и ловушка идемпотентности.
Высота — путь к senior
НольJuniorMiddleSenior
Ты на senior-высоте — в орбитеШесть сценариев, в каждом ты выбираешь статус-код в реальных условиях. Не «что значит 404», а какой код заставит кэши, дашборды и циклы ретраев ниже по потоку принять верное решение.
Цель
Убедиться, что ты можешь подобрать корректный статус под ситуацию и обосновать его — связав нюансы 2xx, словарь 4xx, раздел ответственности 4xx/5xx и правила ретраев/идемпотентности, к которым вёл юнит.
Викторина
Completed
Эндпоинт POST /orders валидирует заказ, синхронно пишет его в БД, и ресурс теперь существует. Какой статус, и что ещё должен нести ответ?
Heads-up 200 прямо ничего не сломает, но недоопределяет: он не утверждает, что появился новый ресурс, и тулинг, который ходит по Location за каноническим URL, ничего не получает. 201 + Location — точный контракт синхронного создания.
Heads-up 202 значит «принято, но ещё не сделано» — для async/очередной работы. Здесь запись синхронна и завершена, поэтому 202 солжёт клиенту, что заказ ещё в обработке.
Heads-up 204 значит успех с сознательно пустым телом. Создание обычно хочет вернуть ресурс (или хотя бы его Location), так что 204 выбрасывает ровно ту информацию, которая клиенту нужна.
Викторина
Completed
Эндпоинт принимает запрос, ставит его в Kafka и возвращается сразу; воркер обрабатывает его через секунды. Какой статус честен?
Heads-up 200 говорит «готово, вот результат» — синхронно и полностью. Работа ещё в очереди, поэтому UI клиента покажет завершённую операцию, которой ещё нигде нет. Это async-vs-sync ложь.
Heads-up 201 утверждает, что ресурс теперь существует. Воркер не отработал, значит, ничего ещё не создано. 202 («принято, не сделано») — честный код.
Heads-up Ничего не упало и ничего не недоступно — запрос успешно принят. 503 сказал бы клиентам отступить и ретраить запрос, который на самом деле прошёл.
Викторина
Completed
Приходит запрос с валидным JSON, все обязательные поля на месте и правильных типов, но quantity = -3 — нарушение бизнес-правила. Какой класс и код подходят лучше всего?
Heads-up 400 сигналит о малформед-синтаксисе — непарсящийся JSON, отсутствующее обязательное поле. Это тело распарсилось чисто; значения семантически неверны. 400 говорит клиенту чинить структуру, когда чинить надо данные. Многие API сводят оба к 400, но различие 400-vs-422 — это то, что говорит клиенту, что чинить.
Heads-up 409 — для столкновения с текущим состоянием ресурса: дубликат, гонка версий. Отдельное плохое значение — не конфликт состояния, а нарушенное бизнес-правило, то есть 422.
Heads-up Плохое входное значение — вина клиента, а не сервера. 500 ошибочно скажет каждому циклу ретраев, что запрос был валиден и стоит ретрая, и засорит дашборды error-rate небагом.
Викторина
Completed
Обратный прокси проксирует запрос в апстрим-сервис, который жив, но возвращает искажённый, обрезанный ответ, который прокси не может распарсить. Какой статус прокси вернёт клиенту?
Heads-up 500 значит, что приложение, обрабатывающее запрос, бросило исключение и не оправилось — его собственный баг. Здесь прокси здоров; вина — малформед-ответ апстрима. 502 распределяет вину верно, а это важно для триажа.
Heads-up 504 — именно таймаут: шлюз ждал апстрим и сдался. Апстрим тут ответил, просто мусором. 502 (плохой ответ) — верный под-код; 504 (нет ответа вовремя) — другой сбой.
Heads-up 503 значит, что сервер сознательно не обслуживает — перегружен, дренится, на обслуживании — и должен нести Retry-After. Плохой ответ апстрима — не сознательная недоступность; это 502.
Викторина
Completed
Клиент упёрся в rate limit, и сервер возвращает 429 с `Retry-After: 30`. Клиент также гоняет общий экспоненциальный бэкофф с джиттером. Что ему делать?
Heads-up Retry-After — это сервер, говорящий тебе ровно, когда его окно откроется. Игнор и ретрай раньше зарабатывает ещё один 429 или бан; ретрай сильно позже тратит ёмкость. Бэкофф с джиттером — фолбэк на случай, когда сервер не дал указаний, а не override.
Heads-up 429 — явное ретраебельное исключение в диапазоне 4xx, и фикс — замедлиться, а не переслать мгновенно. Немедленный ретрай на 429 — ровно то, что бьёт по rate limiter сильнее.
Heads-up 429 временный и ретраебельный по дизайну. Уважить Retry-After и ретраить — корректное поведение; провалить пользователя — выбросить запрос, который пройдёт через мгновения.
Викторина
Completed
Неидемпотентный POST /charge ловит таймаут 504, ключ идемпотентности не отправлен. Списание могло пройти, а могло и нет. Какое поведение клиента корректно?
Heads-up Правило «5xx ретраебельно» предполагает идемпотентность. POST не идемпотентен, а 504 значит, что бэкенд мог завершить списание до того, как шлюз сдался. Слепой ретрай без ключа идемпотентности — ровно то, как это становится двойным списанием.
Heads-up 504 значит, что шлюз перестал ждать, а не что работа упала. Списание могло пройти; объявить отказ может породить дубль ручного платежа поверх реального списания. Состояние неизвестно, а не «упало».
Heads-up Без ключа идемпотентности даже один ретрай может списать дважды, если первая попытка реально прошла. Проблема не в числе ретраев, а в отсутствующем ключе идемпотентности. Добавь ключ — и ретраи станут безопасны.
Итог
Сквозная линия: первая цифра — машинная инструкция, а точный под-код несёт реальную информацию контракта. 2xx делится на 201 (+Location) для синхронного создания, 202 для принято-но-async, 204 для сознательно пустого успеха. Словарь 4xx говорит клиенту, что чинить — 400 (синтаксис) vs 422 (значения) vs 409 (состояние). Под-коды 5xx распределяют вину — 500 твой баг, 502 плохой апстрим, 503 сознательная недоступность, 504 таймаут, где работа могла тайно завершиться. Ретрай 5xx и 429, уважь Retry-After перед бэкоффом и никогда слепо не ретрай неидемпотентный запрос после таймаута — вместо этого тянись за ключом идемпотентности.