Коды ответов: 2xx, 3xx, 4xx, 5xx
↑ 1.2 HTTP и REST для не-разработчиков · ← Предыдущая · → Следующая
Зачем это аналитику и PM
Код ответа — первая развилка бага: чинить запрос, права, сценарий или звать серверную команду. Без кода переписка тонет в скриншоте пустого экрана.
План темы
- самые частые коды (200, 201, 204, 400, 401, 403, 404, 409, 422, 429, 500, 502, 503)
- что делать с каждым
- чья это ошибка
Объяснение
Код ответа — трёхзначное число в стартовой строке. Оно говорит класс исхода, а не текст, который надо показать человеку. Первая цифра задаёт класс: 2 — успех, 3 — идите по другому адресу, 4 — запрос с этой стороны не принят, 5 — сбой там, где запрос обрабатывали.
Как талон в окошке. Зелёная серия значит «сделано» или «принято». Жёлтая — «вас отправили в другое окно». Серия на клиента значит «бланк заполнен не так или у вас нет права». Серия на учреждение значит «окно сломалось, ваш бланк тут ни при чём». Текст на табло может быть вежливым и при этом не совпасть с серией. В разборе верят серии, а текст читают как пояснение.
Частые коды
| Код | Класс | Смысл в сценарии | Куда смотреть сначала |
|---|---|---|---|
| 200 | 2xx | Успех, в теле есть данные | Совпадает ли тело с ожиданием |
| 201 | 2xx | Ресурс создан | Появилась ли сущность и её id |
| 204 | 2xx | Успех без тела | Не ждать JSON |
| 302 | 3xx | Клиенту предлагают другой адрес | Куда ведёт заголовок Location |
| 400 | 4xx | Запрос не разобрали | Состав полей и формат |
| 401 | 4xx | Не представились | Токен, ключ, срок сессии |
| 403 | 4xx | Представились, но нельзя | Роль и правило доступа |
| 404 | 4xx | Ресурс не найден или скрыт | Id, стенд, политика «прятать нет прав» |
| 409 | 4xx | Конфликт состояния | Дубль, гонка, устаревшая версия |
| 422 | 4xx | Синтаксис ясен, правило нарушено | Бизнес-проверка полей |
| 429 | 4xx | Слишком много запросов | Лимит и пауза, не новый заказ |
| 500 | 5xx | Сбой внутри сервера | Команда сервиса и журнал |
| 502 | 5xx | Шлюз не дождался соседней системы | Партнёр или внутренний узел |
| 503 | 5xx | Сервис временно не принимает работу | Повтор позже, без слепого дубля |
Класс 3xx в API встречается реже, чем на сайтах. Код 302 здесь для полноты картины: клиенту говорят новый адрес.
Чья это ошибка и что делать
Коды 4xx чинят на стороне запроса: поля, метод, адрес, допуск, бизнес-правило, частота. Повторять такой вызов без изменения бесполезно, кроме 429, где помогает пауза. Коды 5xx несут команде сервера или владельцу смежной системы. Повтор 5xx иногда уместен, но для оплаты и создания его нельзя делать вслепую: первый запрос мог уже пройти, а ответ потеряться.
401 и 403 путают из-за английского имени. Стандарт называет 401 Unauthorized, хотя смысл ближе к «не аутентифицированы». 403 Forbidden — «вы известны, операция запрещена». В баге пишите число. 404 не всегда значит «записи нет в базе»: часть команд прячет чужой ресурс за 404, чтобы не подтверждать его существование. Это решение по безопасности, его надо знать до приёмки.
400, 409 и 422 все про «клиент прислал не то», но действие аналитика разное. 400 — сообщение кривое. 422 — сообщение поняли, правило предметной области не пустило. 409 — само по себе поле верное, но состояние уже другое: заказ отгрузили, пока его отменяли.
Примеры
Учебный сервис httpbin возвращает ровно тот код, который указан в пути. Это проверка «я вижу код», не ваш заказ.
curl -sS -o /dev/null -w "%{http_code}\n" "https://httpbin.org/status/404"Схема ответа, когда поле поняли, но правило не пустило. Код 422 и текст для человека — разные слои. Точные фразы берут из контракта.
{
"status": 422,
"error": "quantity_exceeds_stock",
"message": "На складе меньше, чем в заказе"
}Поле status внутри JSON не заменяет код HTTP. В баге нужны оба числа, если они вдруг разошлись.
Нюансы и подводные камни
- Успешный код не равен бизнес-успеху.
202или200с статусом «принято» может значить «ещё не оплачено». - Текст
OKпри коде500не бывает в нормальном разборе. Если инструмент показывает только слово, откройте число. - Один экран прячет код за фразой «что-то пошло не так». Для дефекта число всё равно выписывают из вкладки сети.
Практика
Возьмите три исхода сценария «создать заказ»: успех, неверное поле, сбой сервера. Назначьте код и одну фразу для человека.
Ожидаемый результат: успех — 201 или другой код, который назвала команда, не одно слово «ок». Неверное поле — 400 или 422, и сказано, чем они у вас отличаются. Сбой — 5xx без совета пользователю «исправьте количество».
Вопросы с ответами
Чем 401 отличается от 403?
401— клиент не доказал, кто он, или сессия кончилась.403— его узнали, но операцию делать нельзя. В английском имени401слово unauthorized легко прочитать как «нет прав», поэтому в баге пишут число.
404 всегда значит, что записи нет?
Нет. Иногда так скрывают чужой или запрещённый ресурс. Политику «нет прав выглядит как нет записи» команда должна назвать явно, иначе приёмка спорит с безопасностью.
Что делать с 429?
Это лимит частоты, а не дефект поля. Ждут паузу или снижают частоту опроса. Новый заказ «вместо» отклонённого по лимиту легко станет дублем.