Ошибка HTTP 401 Unauthorized¶

Ошибка 401 Unauthorized («Не авторизован») — код состояния HTTP, который сервер возвращает клиенту в ответ на запрос, не сопровождённый корректными учётными данными. Ошибка означает, что запрос был принят сервером, но не аутентифицирован: клиент не предоставил заголовок Authorization, либо предоставленные учётные данные (логин, пароль, API-ключ, токен) неверны, просрочены или недостаточны для доступа к запрашиваемому ресурсу.

Код 401 относится к классу клиентских ошибок 4xx и формально определён в стандарте RFC 7235 (HTTP/1.1: Authentication), который заменил устаревший RFC 2617. Согласно спецификации, ответ сервера с кодом 401 обязан содержать заголовок WWW-Authenticate с одним или несколькими схемами аутентификации, которые сервер принимает для данного ресурса.

¶Отличие от кода 403 Forbidden

Ошибка 401 часто путают с ошибкой 403 Forbidden, однако они означают разное:

При 401 сервер как бы говорит: «Я не знаю, кто вы». При 403 — «Я знаю, кто вы, но вам сюда нельзя». Если повторить запрос к 401-ресурсу с корректными учётными данными, запрос будет выполнен; повтор с теми же данными к 403-ресурсу результат не изменит.

¶Типичные причины возникновения

• Отсутствие заголовка Authorization в запросе к защищённому ресурсу.
• Неверный логин или пароль при базовой аутентификации (Basic Auth).
• Истёкший или отозванный токен доступа (JWT, OAuth-токен, API-ключ).
• Некорректный формат заголовка авторизации (например, отсутствует префикс Bearer или Basic).
• Неверно указанный тип аутентификации в конфигурации клиента.
• Смена учётных данных на сервере при сохранённых старых данных в клиенте или в браузере.
• Проблемы с часами устройства: при аутентификации по времени (например, подписанные запросы AWS) рассинхронизация часов приводит к отклонению подписи.

¶Формат ответа сервера

Минимальный ответ с ошибкой 401 выглядит так:

`` HTTP/1.1 401 Unauthorized WWW-Authenticate: Basic realm="example" Content-Length: 0 ``

При использовании токенов заголовок WWW-Authenticate может содержать схему Bearer:

`` WWW-Authenticate: Bearer realm="api", error="invalid_token" ``

Тело ответа часто содержит JSON с описанием ошибки:

``json { "error": "unauthorized", "message": "Invalid or expired access token" } ``

¶Основные схемы аутентификации, связанные с 401

• Basic Auth — логин и пароль кодируются в Base64 и передаются в заголовке. Простая, но небезопасная без шифрования TLS схема.
• Bearer-токен — в заголовке передаётся JWT или иной токен, выданный сервером аутентификации после успешного входа.
• Digest Auth — пароль не передаётся в открытом виде, вместо него отправляется хеш.
• API-ключи — статические ключи, часто передаются в заголовке X-API-Key; их отсутствие или неверное значение также приводит к 401.

¶Что делать пользователю

Если ошибка 401 появилась в браузере при открытии сайта или веб-приложения, обычно достаточно выполнить вход заново: сессия или cookie могли истечь. В приложениях, работающих с API, необходимо проверить корректность токена и при необходимости получить новый. Иногда помогает очистка кэша браузера или повторная авторизация.

¶Что делать разработчику

На стороне сервера при получении 401 от внешнего API проверяются:

1. Правильность передачи заголовка авторизации (частая ошибка — заголовок не добавлен к запросу).
2. Актуальность токена или ключа (истёк ли срок действия, не отозван ли ключ).
3. Правильность формата (например, Bearer <token> с пробелом).
4. Корректность часов на сервере при подписанных запросах.
5. Не изменился ли эндпоинт или схема аутентификации на стороне провайдера.

На стороне сервера, отдающего 401, проверяется конфигурация middleware аутентификации, корректность хранилища учётных данных и настройки realm.

¶Ошибки, связанные с 401

С кодом 401 связаны и другие ошибки аутентификации: 407 Proxy Authentication Required (требуется аутентификация на прокси-сервере) и 440 Login Timeout (неофициальный код, используемый некоторыми серверами, например IIS, при истечении времени входа).

Источники:

• RFC 7235 — HTTP/1.1: Authentication
• RFC 9110 — HTTP Semantics
• MDN Web Docs — HTTP response status codes: 401 Unauthorized
• OWASP — Authentication Cheat Sheet