Сервис лежал 40 минут из-за одного просроченного токена

MAATRIX

Интеграция работала месяцами без единого сбоя, никто не трогал конфиги — и вдруг все запросы к внешнему сервису начинают падать с 401 или 403. Первая реакция — искать, что сломали в коде или в сети, а причина в это время лежит совсем в другом месте: у временного токена доступа истёк срок жизни, а автообновление, которое должно было выпустить новый, само сломалось задолго до этого и просто никто не заметил. Разберём, как это происходит на практике, почему обычный мониторинг доступности его пропускает и что сделать, чтобы в следующий раз токен обновился за неделю до дедлайна, а не в 3 часа ночи руками.

Симптом: массовые 401 и 403 без видимой причины

Классическая картина: мониторинг присылает алерт, что сервис недоступен или отвечает ошибками — но не полностью лежит, а конкретный участок функциональности. Например, приложение принимает запросы пользователей, отдаёт статику, но любое обращение к внешнему API (платёжный шлюз, CRM, сервис уведомлений, облачное хранилище) валится с 401 Unauthorized или 403 Forbidden. В логах — сплошная стена одинаковых ошибок:

2026-08-27 03:14:02 ERROR [payment-client] POST https://api.provider.com/v2/charges -> 401
2026-08-27 03:14:02 ERROR [payment-client] {"error":"invalid_token","error_description":"Access token expired"}
2026-08-27 03:14:03 ERROR [payment-client] POST https://api.provider.com/v2/charges -> 401
2026-08-27 03:14:03 ERROR [payment-client] {"error":"invalid_token","error_description":"Access token expired"}

Важная деталь, которая сразу отличает этот сценарий от «что-то поломали в деплое»: ошибка бьёт ровно по одной интеграции, все остальные части системы работают штатно, и в git-истории за последние дни нет ни одного коммита, трогающего этот участок кода или переменные окружения. Именно это сочетание — «ничего не меняли, а всё легло» — обычно и указывает на просроченный секрет, а не на баг.

Проверка руками подтверждает диагноз быстрее любых логов:

curl -s -o /dev/null -w "%{http_code}\n" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  https://api.provider.com/v2/ping
# 401

Если тот же запрос с текущим токеном из .env отдаёт 401, а сам эндпоинт при этом жив (проверяется без авторизации или с заведомо свежим токеном), проблема локализована — дело не в сети, не в самом провайдере и не в правах доступа, а именно в токене на руках у вашего сервиса.

Причина: истёк временный токен доступа

Большинство внешних API сегодня работают не с вечным API-ключом, а со связкой access-токен + refresh-токен (классический OAuth2) или с ключом, у которого явно прописан срок жизни (TTL) — час, сутки, 30 или 90 дней. Access-токен — короткоживущий, он и используется в каждом запросе, а refresh-токен — долгоживущий, и его задача — раз в какое-то время сходить в сервис авторизации и получить новый access-токен без участия человека:

curl -s -X POST https://api.provider.com/oauth/token \
  -d grant_type=refresh_token \
  -d refresh_token=$REFRESH_TOKEN \
  -d client_id=$CLIENT_ID \
  -d client_secret=$CLIENT_SECRET

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

Проблема начинается там, где сам refresh перестаёт срабатывать. Здесь есть два типичных сценария:

• Автообновление не настроено вовсе. Кто-то интегрировал API «на скорую руку» — вписал долгоживущий на момент выпуска токен прямо в .env или в секреты CI/CD, всё заработало, и про то, что у него вообще есть срок годности, все благополучно забыли. Токен тикает молча, без предупреждений, пока однажды не истекает.
• Автообновление сломалось незаметно. Логика обновления есть, но у неё есть собственная точка отказа: истёк сам refresh-токен. Это особенно коварно там, где refresh-токен имеет не фиксированный, а «скользящий» срок действия — он продлевается каждый раз, когда им реально пользуются, но аннулируется, если им не пользовались достаточно долго (у разных провайдеров порог разный, у некоторых счёт идёт на месяцы неиспользования). Пока сервис активно рефрешит токены каждый день, всё живёт вечно. Но если, например, интеграция временно перестала дёргаться (сервис отключили на время миграции, фича ушла в фичефлаг, тестовый контур простаивал по выходным), рефреш-цикл прерывается — а когда его снова включают, оказывается, что и refresh-токен уже мёртв, и обновиться нечем.

Второй сценарий разбирает и добивает команды сильнее первого именно потому, что выглядит парадоксально: «у нас же стоит автообновление, как оно могло не сработать» — а оно не срабатывает не потому, что сломан код, а потому что кончился сам материал, из которого обновление могло бы что-то получить.

Почему это осталось незамеченным до последнего момента

Стандартный мониторинг в такой ситуации молчит до самого падения — и на то есть конкретная причина: он проверяет факт доступности («сервис отвечает 200») и факт ошибки после того, как она уже случилась, но никто не проверяет саму «дистанцию до обрыва» — сколько времени осталось жить конкретному токену.

Ситуация усугубляется тем, что access-токен с коротким TTL (час, сутки) обновляется настолько часто, что любая аномалия в этом процессе тонет в общем потоке: если один запрос на обновление не прошёл, а следующий через час прошёл нормально — никто этого не заметит, алерт никто не настраивал, ошибка не долетела дальше debug-лога. Проблема копится незаметно ровно до того дня, когда либо кончается refresh-токен целиком, либо curl к эндпоинту обновления начинает валиться по совсем другой причине (сменился сертификат провайдера, поменялся формат ответа) — и тогда рушится сразу всё.

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

Экстренные меры: ручное обновление токена

Когда сервис уже лежит, время дороже элегантности — задача в моменте одна: вернуть работоспособность руками, разобраться потом. Порядок действий обычно такой:

1. Подтвердить диагноз. Проверить exp (время истечения) в текущем access-токене, если это JWT:

echo $ACCESS_TOKEN | cut -d. -f2 | base64 -d 2>/dev/null | python3 -m json.tool
# {
#   "sub": "service-account-42",
#   "iat": 1755000000,
#   "exp": 1756900000
# }
date -d @1756900000   # сравнить с текущим временем

1. Попробовать штатный refresh руками, если refresh-токен ещё жив — часто проблема именно в том, что автоматический процесс не запустился (упал крон, зафейлился systemd timer), а не в том, что сам механизм невозможен:

systemctl status token-refresh.timer
journalctl -u token-refresh.service --since "2 hours ago"

1. Если рефреш-токен тоже мёртв — идти в консоль провайдера или в личный кабинет CRM/платёжного шлюза и выпускать новую пару токенов вручную. Это единственный надёжный путь, если автоматическая цепочка полностью разорвана: ни один скрипт не восстановит токен, которого больше не существует на стороне провайдера.

1. Обновить секрет там, где он реально используется — в .env на сервере, в Vault/Secrets Manager, в переменных CI/CD — и перезапустить сервис, чтобы он подхватил новое значение:

vim /opt/myapp/.env   # или secret-tool, vault kv put, aws secretsmanager put-secret-value
systemctl restart myapp.service
curl -s -o /dev/null -w "%{http_code}\n" https://api.provider.com/v2/ping -H "Authorization: Bearer $NEW_TOKEN"

1. Убедиться, что интеграция реально восстановилась, а не просто перестала кричать в логи — прогнать тестовый запрос конца в конец (например, тестовый платёж в песочнице провайдера, а не только пинг эндпоинта), потому что 200 на /ping не всегда означает, что рабочий сценарий тоже прошёл.

Если у вас уже настроены алерты в Telegram, стоит сразу же добавить в тот же канал отдельное уведомление именно про эту интеграцию — пока инцидент свеж в памяти, это самый простой момент, чтобы закрыть дыру в мониторинге, а не откладывать «на потом», которое, как правило, наступает только после следующего падения.

Профилактика: мониторинг TTL токена, а не факта его смерти

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

Скрипт-проверка TTL. Простейший вариант — крон-задача, которая раз в сутки декодирует токен (или спрашивает у провайдера через introspection-эндпоинт, если он есть) и сравнивает exp с текущим временем:

#!/bin/bash
# check-token-ttl.sh
EXP=$(echo "$ACCESS_TOKEN" | cut -d. -f2 | base64 -d 2>/dev/null | python3 -c "import sys,json; print(json.load(sys.stdin)['exp'])")
NOW=$(date +%s)
DAYS_LEFT=$(( (EXP - NOW) / 86400 ))

if [ "$DAYS_LEFT" -le 7 ]; then
  curl -s -X POST "https://api.telegram.org/bot$TG_BOT_TOKEN/sendMessage" \
    -d chat_id=$TG_CHAT_ID \
    -d text="⚠️ Токен для api.provider.com истекает через $DAYS_LEFT дн. Проверьте автообновление."
fi

Этот же скрипт полезно повесить и на healthchecks.io или аналогичный сервис пассивного мониторинга — если крон вообще не отработал (сервер перезагрузили, systemd timer сломался), об этом тоже придёт сигнал, а не тишина. Подробно про этот подход — в статье про мониторинг cron-задач через healthchecks.io.

Мониторинг успешности самого refresh-процесса — отдельная и не менее важная часть. Мало верить, что автообновление «должно» работать — нужно видеть, что оно реально сработало последний раз и когда именно. Практичный вариант — писать метку времени последнего успешного обновления в отдельный файл или в Redis/Prometheus-метрику:

# в конце успешного refresh-скрипта
date +%s > /var/lib/myapp/last_token_refresh.ts

и отдельным алертом проверять, что эта метка не «застряла» дольше ожидаемого интервала:

LAST=$(cat /var/lib/myapp/last_token_refresh.ts)
NOW=$(date +%s)
if [ $(( (NOW - LAST) / 3600 )) -gt 6 ]; then
  echo "Refresh не выполнялся больше 6 часов — проверить token-refresh.service"
fi

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

Что делать с самим refresh-токеном, если у него скользящий срок действия. Если провайдер аннулирует refresh-токен при долгом неиспользовании, самая надёжная защита — дёргать refresh принудительно по расписанию, даже если access-токен ещё не истёк, чтобы «скользящий» счётчик никогда не подходил близко к порогу:

# systemd timer: обновлять токен каждые 12 часов независимо от TTL access-токена
[Timer]
OnCalendar=*-*-* 00,12:00:00
Persistent=true

Persistent=true здесь важен отдельно: если сервер был выключен или перезагружался в момент срабатывания таймера, systemd досрочно запустит пропущенный прогон при следующем старте, а не будет молча ждать следующего расписания.

Документируйте сам факт существования секрета с ограниченным сроком. Отдельная страница или комментарий в репозитории — какой это токен, у какого провайдера, какой у него режим истечения (фиксированный TTL или скользящий), кто отвечает за продление и где лежит скрипт автообновления — стоит на порядок дешевле, чем повторное расследование той же истории через год другой командой, которая уже не помнит контекст первого инцидента.

Ни один из этих пяти пунктов не требует сложной инфраструктуры — это крон-задачи, systemd-таймеры и один Telegram-бот. Разница между «узнали за неделю» и «узнали, когда упало ночью» — это не другой стек технологий, а всего лишь несколько строк, которых не хватало.

Частые вопросы