Какие есть стандарты и где искать информацию о статус кодах HTTP
Что проверяют
Знаете ли вы первоисточник и умеете ли выбрать код для конкретной ситуации, когда пишете спецификацию API. Для аналитика следом почти всегда идёт практика: какой код вернуть при ошибке валидации, при отсутствии прав, при конфликте версий.
Как отвечать
Сначала источники:
- IETF и RFC: HTTP стандартизирует IETF, а не W3C. Действующий документ про семантику, методы и коды это RFC 9110 (2022 год), он заменил RFC 7231. Рядом RFC 9111 про кеширование и RFC 9112, 9113, 9114 про HTTP/1.1, HTTP/2 и HTTP/3;
- реестр IANA: HTTP Status Code Registry, полный список кодов со ссылкой на RFC, где каждый описан. Например,
429 Too Many Requestsпришёл из RFC 6585; - MDN: удобный справочник с примерами, но вторичный. Спорный вопрос решается по RFC;
- RFC 9457: формат Problem Details (
application/problem+json) для тела ошибки. Пригодится, когда описываете, что вернуть вместе с кодом.
Потом классы: 1xx информационные, 2xx успех, 3xx перенаправление, 4xx ошибка клиента, 5xx ошибка сервера. Клиент, не знающий конкретного кода, обязан трактовать его как x00 того же класса.
И сразу пары, в которых путаются: 401 означает «не аутентифицирован», 403 «аутентифицирован, но нельзя»; 400 про неразбираемый запрос, 422 Unprocessable Content про верный синтаксис с неверными данными; 409 про конфликт состояния; 201 с заголовком Location после создания; 204 без тела. В OpenAPI это оформляется блоком responses у каждого эндпоинта.
Где спотыкаются
Ссылаются на RFC 2616 или 7231 как на действующие. Оба заменены, а в новой редакции, например, 422 переехал из WebDAV в основной стандарт.
Закладывают в требования 200 с полем "error" в теле. Мониторинг, кеши и ретраи клиента видят успех, и ошибка теряется.
Путают 301/302 с 307/308. Первые исторически позволяют клиенту сменить метод на GET, вторые сохраняют метод и тело, поэтому для перенаправления POST нужны именно они.