Ошибка временной метки Binance API -1021: исправляем рассинхронизацию часов в самостоятельно размещённом торговом боте
Самостоятельно размещённый торговый бот может правильно подписать запрос, но Binance всё равно его отклонит. Ошибка -1021 указывает на проблему с временной меткой: время подписанного запроса выходит за пределы допустимого окна Binance или опережает серверное время. Обычно исправлять нужно не код торговой стратегии, а машину, на которой работает бот. Если вы ищете, как исправить ошибку Binance API -1021, сначала проверьте часы системы, а не меняйте торговую логику.
Вносите изменения по одному. Сначала зафиксируйте ошибку, затем проверьте часы системы и восстановите синхронизацию времени — и только после этого меняйте обработку временных меток или recvWindow. Такой порядок поможет не скрыть сбой системных часов, просто увеличив окно допустимого времени запроса.
1. Убедитесь, что ошибка -1021 связана со смещением часов
Изучите полный текст ответа, а не только HTTP-статус или сокращённую запись в журнале. Код и сообщение об ошибке API Binance должны указывать, что временная метка выходит за пределы допустимого окна или опережает серверное время; это поможет понять, почему Binance отклоняет запрос из-за временной метки.
Это не то же самое, что некорректная подпись, отсутствие API-ключа или недостаток прав. Такие проблемы обычно сопровождаются другими кодами или сообщениями API. Если вы получили -1021, сначала проверьте временную метку подписи, часы сервера и настроенное значение recvWindow. Не начинайте с замены ключей или изменения прав торговли.
Также проверьте, что запрос действительно подписывается. Для публичных запросов рыночных данных может использоваться другой способ аутентификации, тогда как для доступа к аккаунту и работы с ордерами обычно нужны подписанные запросы. Если бот не справляется только с подписанными запросами, это важная зацепка.
2. Воспроизведите ошибку одним подписанным запросом
На время расследования приостановите размещение ордеров. Для проверки используйте минимальный подписанный запрос к эндпоинту только для чтения, к которому у вашего API-ключа есть доступ. Так вы сможете собрать данные, не создавая и не отменяя ордера. Если у ключа нет доступа к этому эндпоинту, выберите другой эндпоинт только для чтения, поддерживаемый используемой версией Binance API.
Зафиксируйте точную временную метку запроса, эндпоинт, статус ответа, код и текст ошибки Binance, а также время отправки запроса из процесса. Удалите из журналов API-ключ, подпись, данные аккаунта и любые другие секреты. Не публикуйте подписанный URL или полный заголовок аутентификации в открытых обсуждениях и чатах.
Сведите проверку к минимуму.
Запускайте её в той же среде процесса, где возникла ошибка. Часы на хосте могут быть настроены правильно, а контейнер, виртуальная машина или рабочий процесс — использовать другую среду выполнения. Если после корректировки часов один запрос только для чтения проходит успешно, сравните его временную метку и ответ с зафиксированной ошибкой и лишь затем перезапускайте основной цикл торговли.
3. Сравните часы хоста с надёжным источником времени
Проверьте время UTC и состояние синхронизации на той машине или хосте контейнера, где работает бот. В Linux команды вроде date -u и timedatectl status показывают время UTC и позволяют проверить, включена ли системная синхронизация времени. Доступные команды зависят от дистрибутива и установленной службы времени.
Не путайте отображение часового пояса с рассинхронизацией часов. Хост с локальным часовым поясом может показывать другое время, чем UTC, но при этом указывать на тот же момент времени. Сравнивайте значения UTC или метки времени Unix, а не только часы на рабочем столе.
Обычно контейнеры используют системные часы хоста, а не собственные, однако поведение зависит от платформы и среды выполнения. Проверьте также узел или виртуальную машину, на которых запущен контейнер. В оркестрационных средах выясните, какой именно рабочий узел обработал запрос с ошибкой: проверка другого узла может показать корректное время и не объяснить проблему.
Ищите измеримое смещение и проверяйте состояние синхронизации — правдоподобно выглядящей даты недостаточно. Даже отклонения на несколько секунд может хватить для отклонения временной метки — в зависимости от допустимого окна запроса и состояния сети.
4. Восстановите синхронизацию времени на хосте, где работает бот
Используйте службу синхронизации времени, поддерживаемую хостом. В системах под управлением systemd проверьте systemd-timesyncd или настроенную альтернативу, например Chrony. Не считайте, что включённая служба обязательно является активным источником времени. После применения обычной для этого хоста конфигурации проверьте состояние службы и отображаемый ею статус синхронизации.
На облачной виртуальной машине убедитесь, что служба времени гостевой ОС работает с рекомендованным провайдером источником времени. Если виртуальную машину приостанавливали, возобновляли, переносили или восстанавливали из снимка, ещё раз проверьте часы, прежде чем запускать бота. В некоторых средах время корректируется постепенно, поэтому процесс, запущенный сразу после резкого изменения часов, может ещё некоторое время неправильно подписывать запросы.
Если бот работает в контейнере, восстановите синхронизацию на хосте или узле оркестрации, а не пытайтесь менять часы контейнера. Обычно контейнеры не имеют прав на изменение системного времени, и предоставлять такие права торговому боту — плохой обходной путь. После восстановления синхронизации убедитесь, что на фактическом хосте среды выполнения отображается активный статус синхронизации. Одной отметки «включено» недостаточно: она не подтверждает, что хост связался с источником времени.
Перезапускайте бота только после проверки часов хоста. Затем повторите тот же запрос только для чтения и сохраните ответ. Если ошибка осталась, сравните временную метку запроса со временем сервера Binance, прежде чем менять код подписи бота.
5. Измерьте расхождение с временем сервера Binance перед подписанием запросов
В Binance есть публичный эндпоинт серверного времени. Используйте его, чтобы проверить, какое время сообщает сервер. Выполните запрос непосредственно перед проверкой или во время неё и зафиксируйте время сервера и локальное время до и после запроса. Так вы сможете напрямую сравнить время сервера с часами, используемыми ботом.
На результат сравнения влияет задержка сети. Для приблизительной оценки зафиксируйте локальное время отправки и получения ответа, а затем сравните время Binance со средним значением между ними. Например, если запрос отправлен в локальное время t1 и получен в t2, используйте среднее между t1 и t2 как приблизительную оценку локального времени в момент формирования ответа сервером. Оценка будет неточной: задержка в разных направлениях может отличаться, а время обработки запроса эндпоинтом не обязательно равно нулю.
Повторите измерение несколько раз и ориентируйтесь на стабильные результаты с небольшим временем полного обмена. Не считайте единичный ответ с большой задержкой надёжным показанием времени.
Если часы хоста заметно расходятся с оценкой серверного времени, сначала восстановите синхронизацию. Коррекция на уровне приложения может помочь компенсировать небольшое измеренное расхождение, но не должна навсегда заменять исправно работающую службу времени на хосте.
6. Настройте безопасную коррекцию смещения и recvWindow
Если боту нужна коррекция смещения, рассчитайте её на основе повторных измерений серверного времени и применяйте при формировании подписанной временной метки. Храните корректировку в памяти или задавайте её через контролируемый параметр конфигурации, обновляйте по расписанию и записывайте в журнал измеренное смещение и временную метку каждого неудачного запроса. Не задавайте постоянное значение, взятое из одной проверки: задержка сети и состояние хоста могут меняться.
Применяйте смещение до подписания запроса. Временная метка в подписываемых параметрах должна совпадать с той, которая учитывалась при создании подписи. Если изменить её после подписания, подпись станет недействительной. Прежде чем разрешать боту размещать ордера, проверьте этот порядок на эндпоинте только для чтения.
Небольшое увеличение recvWindow может компенсировать обычную задержку сети или незначительные колебания времени. Но оно не исправит постоянное расхождение системных часов. Слишком большое окно также может сделать допустимыми запросы, задержанные дольше необходимого. Поэтому выбирайте наименьшее значение, которое подходит измеренной задержке бота и требованиям API.
Используйте только один способ коррекции за раз. Если часы хоста синхронизированы, а измеренное смещение близко к нулю, удалите ненужную корректировку на уровне приложения, а не складывайте смещение серверного времени с коррекцией другой библиотеки. Прежде чем добавлять собственный код, проверьте, как клиентская библиотека обрабатывает временные метки.
7. Проверьте восстановление работы и предотвратите повторную рассинхронизацию
Повторите тот же подписанный запрос только для чтения и убедитесь, что в ответе больше нет -1021. Сравните его временную метку, измеренное смещение относительно серверного времени и время полного обмена с предыдущим запросом, завершившимся ошибкой. И только после этого возобновляйте обработку ордеров — желательно в тестовом режиме или режиме пониженного риска, если ваша система это позволяет.
Записывайте в журнал имя хоста или узла, локальную временную метку, измеренное смещение и код ошибки API. Настройте оповещение при повторяющихся ошибках времени, а не при единичном случае: серия ошибок после перезагрузки может указывать, что синхронизация ещё не завершилась, а регулярные сбои на одном узле — на локальную проблему хоста.
Повторно проверяйте часы после приостановки и перезагрузки виртуальных машин, миграции контейнеров и перезапуска службы времени. Если после изменения хоста ошибки вернулись, остановите размещение ордеров и проверьте узел, обработавший запрос, прежде чем увеличивать recvWindow. Это поможет не допустить, чтобы из-за временной инфраструктурной проблемы и устаревших часов бот начал отправлять поток отклонённых ордеров.
Чтобы понять, как синхронизировать время для торгового бота Binance, сначала настройте и проверьте службу времени на хосте или узле, где он запущен, а затем убедитесь, что подписанный запрос использует актуальную временную метку.
