HTTP 401 Unauthorized: нужна или не пройдена аутентификация

Код 401 означает, что для доступа к ресурсу нужна аутентификация, а предоставленные данные отсутствуют или недействительны. Сервер вместе с ответом обычно сообщает, какую схему ожидает: базовую, по токену и так далее. Название Unauthorized исторически неудачно: по смыслу это «не аутентифицирован», то есть сервер не знает, кто вы.

Это главное отличие от 403: при 403 сервер понимает, кто вы, но действие запрещено. При 401 личность не установлена.

Чаще всего срок сеанса закончился, и нужно войти заново. Затем идут неверный пароль или логин, отключённая учётная запись, устаревшие сохранённые данные в браузере или менеджере паролей, а также временное ограничение входа после нескольких неудачных попыток.

При обращении к внутренним сервисам с базовой аутентификацией браузер показывает окно с запросом имени и пароля, а неверный ввод приводит к повторному появлению 401. Сюда же относятся ситуации, когда cookie сеанса удалены или не отправляются из-за настроек приватности или расширений.

Выйдите и войдите снова. Проверьте раскладку и регистр при вводе пароля. Очистите cookie для этого сайта и повторите вход. Убедитесь, что время на устройстве верное: для одноразовых кодов и токенов это существенно.

Если вы не помните пароль, воспользуйтесь восстановлением доступа. Если окно с логином не появляется и вы видите пустую страницу, попробуйте другой браузер. Обратите внимание, что после нескольких неудачных попыток сервис может временно закрыть вход: подождите и повторите.

Если вы пользуетесь корпоративной учётной записью, проверьте у администратора, не отключена ли она и не изменилась ли политика входа.

Причин 401 в API много: не передан заголовок Authorization, ошибка в формате, истёкший или отозванный токен, неверная подпись, неправильное окружение, когда токен из тестовой среды используется в рабочей. Проверьте заголовок в запросе: не теряется ли он при перенаправлениях или на промежуточном промежуточный сервер, и не отбрасывается ли он балансировщиком.

Следите за сроком жизни токена и обновляйте его заранее. В ответе возвращайте заголовок с описанием схемы и по возможности краткий код причины, но без раскрытия лишних подробностей о системе. Не путайте 401 с 403: если пользователь известен, но прав нет, верните 403.

Если вход не работает у многих пользователей сразу, вероятно, сервис имеет сбой в системе входа: сломался провайдер идентификации, изменились ключи подписи токенов, истёк сертификат. В этом случае повторные попытки не помогут, а лишние неудачные входы приводят к временному ограничению входа.

Сообщите в поддержку время и точный текст ошибки. Не отправляйте пароли и токены в переписке: достаточно описать шаги и код. Если сервис публикует страницу состояния, сначала посмотрите её: иногда проблема уже описана.

Способ аутентификации влияет на то, как выглядит ошибка. При базовой схеме браузер показывает окно с логином, и повторное появление окна означает неверные данные. При токенах в заголовке сообщение получает приложение, а не человек, и в интерфейсе оно проявляется как «сессия истекла».

При cookie-сеансах 401 иногда возникает, если cookie не отправляется: включены строгие настройки приватности, сайт открыт по другому адресу, чем раньше, или браузер блокирует сторонние cookie в сценарии встраивания. Проверьте, что вы используете один и тот же адрес сайта, включая наличие или отсутствие «www», и что защита от отслеживания не мешает работе основного входа.

Порядок действий коротко: Выйти и войти заново; проверить логин, пароль и раскладку; очистить cookie сайта; проверить дату на устройстве; восстановить пароль при необходимости. Разработчику: проверить заголовок Authorization, срок токена, среду, прохождение заголовка через промежуточный сервер и правильность схемы. Различайте 401 и 403 в ответах: это упрощает жизнь и пользователям, и коллегам.