HTTP статус-коды: предсказуемый контракт API

HTTP статус-коды — часть контракта API, а не просто текст для DevTools. На них опираются клиенты, кеши, прокси, мониторинг и ретраи. По коду должно быть понятно, ошибся ли клиент, упала ли зависимость или нужно просто повторить запрос позже.

Начинайте с результата операции

Для обычных ресурсных endpoint лучше оставить успешные ответы предсказуемыми:

• 201 Created после создания ресурса; по возможности добавьте Location;
• 200 OK, когда чтение или обновление возвращает представление;
• 204 No Content, когда обновление или удаление успешно, но тело ответа не нужно.

Не возвращайте 200 для любой операции с ошибкой, спрятанной в JSON. Тогда HTTP-клиенты, кеши, наблюдаемость и интеграции теряют полезный сигнал.

Отделяйте ошибку запроса от ошибки предметной области

400 Bad Request нужен для некорректного синтаксиса: битого JSON, недопустимого заголовка или запроса, который сервер не может разобрать. 422 Unprocessable Content — для успешно разобранного запроса, в котором не прошли значения полей или бизнес-правила. Дубликат уникального значения, устаревшая версия или другой конфликт с текущим состоянием ресурса обычно означает 409 Conflict.

Авторизация тоже разделяется. Возвращайте 401 Unauthorized, когда credentials отсутствуют или неверны, и 403 Forbidden, когда вызывающий уже определён, но действие ему недоступно. Стабильное значение не заставит клиент просить повторный вход там, где на самом деле не хватает роли.

Делайте временные условия понятными клиенту

Клиент может безопасно отреагировать на временную проблему, только если сервер прямо её обозначил. Для 429 Too Many Requests и 503 Service Unavailable добавляйте Retry-After, когда известна задержка. Прокси, получивший некорректный ответ upstream-сервиса, возвращает 502 Bad Gateway; если он слишком долго ждёт upstream — 504 Gateway Timeout.

Для условной записи требуйте If-Match: при его отсутствии отвечайте 428 Precondition Required, а при несовпавшем ETag — 412 Precondition Failed. Так неявный last-write-wins превращается в разрешимый конфликт.

Держите общий справочник рядом

В инструменте HTTP статус-кодов можно найти зарегистрированный код, посмотреть связанные ответы, скопировать шаблон обработки на шести языках и проверить ответ CORS-доступного endpoint прямо в браузере.

Связанные инструменты

HTTP статус-кодыИщите зарегистрированные HTTP-коды, копируйте обработку на шести языках, тестируйте CORS-доступный endpoint и выбирайте ответы для API.API и веб-песочницаПревращайте команды cURL в код на JavaScript, Python, PHP или Go, либо открывайте живое WebSocket-соединение и наблюдайте за сообщениями — прямо в браузере.Webhook Signature VerifierПроверка подписей webhook для семи провайдеров: точная подписываемая строка, окно защиты от replay и экспорт кода верификации для Node, Python, PHP и Go.