Binance API -1021: naprawa błędu czasu

Błąd znacznika czasu Binance API -1021: jak naprawić rozbieżność zegara w samodzielnie hostowanym bocie tradingowym

Samodzielnie hostowany bot tradingowy może poprawnie podpisać żądanie, a mimo to Binance je odrzuci. Błąd -1021 wskazuje na problem ze znacznikiem czasu: czas podpisanego żądania wykracza poza akceptowane przez Binance okno albo wyprzedza czas serwera. Naprawę zwykle należy zacząć od maszyny, na której działa bot, a nie od kodu strategii. Jeśli szukasz informacji, jak naprawić błąd Binance API -1021, najpierw sprawdź zegar środowiska uruchomieniowego, zamiast zmieniać logikę handlową.

Wprowadzaj po jednej zmianie naraz. Najpierw zarejestruj błąd, następnie sprawdź zegar środowiska uruchomieniowego i przywróć synchronizację czasu, a dopiero potem zmieniaj obsługę znaczników czasu lub parametr recvWindow. Taka kolejność pomaga uniknąć maskowania problemu z zegarem hosta przez zwiększenie okna żądania.

1. Potwierdź, że -1021 oznacza błąd różnicy czasu

Odczytaj pełną treść odpowiedzi, a nie tylko kod statusu HTTP lub skrócony wpis w logu. Kod i komunikat błędu API Binance powinny wskazywać, że znacznik czasu wykracza poza dozwolone okno albo wyprzedza czas serwera. Jeśli zastanawiasz się, co oznacza błąd znacznika czasu Binance -1021, właśnie ta treść odpowiedzi pozwoli potwierdzić, czy problem dotyczy różnicy czasu.

Taka odpowiedź różni się od błędnego podpisu, braku klucza API czy problemu z uprawnieniami. Te problemy zwykle powodują inne kody lub komunikaty błędów API. Jeśli kod to -1021, najpierw sprawdź podpisany znacznik czasu, zegar serwera i skonfigurowany parametr recvWindow; nie reaguj od razu na przykład przez zmianę kluczy czy uprawnień handlowych.

Upewnij się też, że nieudane wywołanie jest podpisywane. Publiczne żądania dotyczące danych rynkowych mogą korzystać z innego mechanizmu uwierzytelniania, podczas gdy punkty końcowe konta i zleceń zazwyczaj wymagają podpisanych żądań. Jeśli bot zawodzi tylko przy podpisanych wywołaniach, to cenna wskazówka.

2. Odtwórz błąd za pomocą jednego podpisanego żądania

Wstrzymaj składanie zleceń na czas diagnozy. Użyj minimalnego, tylko do odczytu, podpisanego punktu końcowego, do którego Twój klucz API ma dostęp. Dzięki temu podczas zbierania danych nie utworzysz ani nie anulujesz zleceń. Jeśli klucz nie ma uprawnień do tego punktu końcowego, wybierz inny punkt tylko do odczytu obsługiwany przez wersję API Binance używaną przez bota.

Zapisz dokładny znacznik czasu żądania, punkt końcowy, status odpowiedzi, kod i komunikat błędu Binance oraz moment wysłania żądania przez proces. Usuń z logów klucz API, podpis, dane konta i wszelkie inne poufne informacje. Nigdy nie wklejaj podpisanego adresu URL ani pełnego nagłówka uwierzytelniania do publicznego zgłoszenia lub czatu.

Ogranicz test do minimum.

Uruchom go w tym samym środowisku procesu, w którym wystąpił błąd. Zegar hosta może być poprawny w powłoce, a jednocześnie kontener, maszyna wirtualna lub proces roboczy może korzystać z innej konfiguracji środowiska uruchomieniowego. Jeśli po korekcie zegara jedno żądanie tylko do odczytu zakończy się powodzeniem, porównaj jego znacznik czasu i odpowiedź z zarejestrowanym błędem, zanim ponownie uruchomisz pełną pętlę handlową.

3. Porównaj zegar hosta z zaufanym źródłem czasu

Sprawdź czas UTC i stan synchronizacji na rzeczywistej maszynie lub hoście kontenera, na którym działa bot. W systemie Linux polecenia takie jak date -u i timedatectl status mogą wyświetlić czas UTC oraz informację, czy synchronizacja czasu systemowego jest aktywna. Dostępne polecenia zależą od dystrybucji i zainstalowanej usługi czasu.

Nie myl różnicy w wyświetlanej strefie czasowej z rozbieżnością zegara. Host skonfigurowany dla lokalnej strefy czasowej może pokazywać inną godzinę niż UTC, a mimo to wskazywać tę samą chwilę. Porównuj wartości UTC lub znaczniki czasu Unix, a nie samą godzinę wyświetlaną na zegarze komputera.

Kontenery zwykle korzystają z zegara systemowego hosta, zamiast utrzymywać własny, ale szczegóły zależą od platformy i środowiska uruchomieniowego. Sprawdź również węzeł lub maszynę wirtualną, na której działa kontener. W środowiskach orkiestracyjnych ustal, który konkretnie worker obsłużył nieudane żądanie. Sprawdzenie innego węzła może dać poprawny wynik, który nie wyjaśni problemu.

Sprawdź, czy występuje mierzalna różnica czasu i jaki jest stan synchronizacji — nie polegaj wyłącznie na dacie, która „wygląda prawidłowo”. Zegar opóźniony lub przyspieszony o kilka sekund może wystarczyć, by żądanie zostało odrzucone, zależnie od okna żądania i warunków sieciowych.

4. Przywróć synchronizację czasu na rzeczywistym hoście środowiska uruchomieniowego

Korzystaj z usługi synchronizacji czasu obsługiwanej przez hosta. W systemie zarządzanym przez systemd sprawdź systemd-timesyncd lub skonfigurowaną alternatywę, taką jak Chrony. Nie zakładaj, że włączenie usługi oznacza, że jest ona aktywnym źródłem czasu. Po zastosowaniu standardowej konfiguracji hosta sprawdź stan usługi i zgłaszany przez nią stan synchronizacji.

W przypadku maszyny wirtualnej w chmurze upewnij się, że usługa czasu gościa działa zgodnie z zaleceniami dostawcy. Jeśli maszyna została wstrzymana, wznowiona, przeniesiona lub odtworzona z migawki, sprawdź jej zegar, zanim ponownie uruchomisz bota. Niektóre środowiska korygują czas stopniowo, więc proces uruchomiony zaraz po dużym skoku zegara może przez krótki czas nadal niepoprawnie podpisywać żądania.

W przypadku kontenera przywróć synchronizację na hoście lub węźle orkiestracji, zamiast próbować zmieniać zegar kontenera. Kontenery zazwyczaj nie mają uprawnień do zmiany czasu systemowego, a przyznawanie takich uprawnień botowi tradingowemu nie jest dobrym rozwiązaniem zastępczym. Po przywróceniu synchronizacji sprawdź, czy rzeczywisty host środowiska uruchomieniowego zgłasza aktywną synchronizację. Sam status „włączona” nie dowodzi, że host połączył się ze źródłem czasu.

Uruchom ponownie bota dopiero po sprawdzeniu zegara hosta. Następnie ponownie wykonaj to samo żądanie tylko do odczytu i zapisz odpowiedź. Jeśli błąd nadal występuje, porównaj znacznik czasu żądania z czasem serwera Binance, zanim zmienisz kod podpisywania w bocie.

5. Zmierz różnicę czasu względem serwera Binance przed podpisywaniem żądań

Binance udostępnia publiczny punkt końcowy z czasem serwera. Odpytaj go bezpośrednio przed kontrolowanym testem lub w jego trakcie i zapisz zarówno zwrócony znacznik czasu serwera, jak i lokalny czas zarejestrowany w pobliżu żądania. Dzięki temu bezpośrednio porównasz czas serwera z zegarem używanym przez bota.

Opóźnienia sieciowe wpływają na wynik porównania. Przybliżoną wartość można oszacować, zapisując lokalny czas wysłania i odebrania odpowiedzi, a następnie porównując zwrócony przez Binance czas z punktem środkowym między tymi wartościami. Na przykład, jeśli żądanie wychodzi przy lokalnym czasie t1 i wraca przy t2, za przybliżony lokalny czas wygenerowania odpowiedzi przez serwer przyjmij środek między t1 i t2. Otrzymana różnica jest szacunkowa, ponieważ trasy sieciowe mogą być asymetryczne, a czas przetwarzania po stronie punktu końcowego nie musi wynosić zero.

Powtórz pomiar kilka razy i oprzyj się na stabilnym wyniku uzyskanym dla odpowiedzi o krótkim czasie podróży w obie strony. Pojedynczej opóźnionej odpowiedzi nie traktuj jako wiarygodnego odczytu zegara.

Jeśli zegar hosta wyraźnie różni się od oszacowania czasu serwera, najpierw przywróć synchronizację. Korekta po stronie aplikacji może pomóc skompensować niewielkie, zmierzone różnice, ale nie powinna na stałe zastępować sprawnie działającej usługi czasu hosta.

6. Zastosuj bezpieczną strategię korekty czasu i parametru recvWindow

Jeśli bot wymaga korekty, oblicz ją na podstawie powtarzanych pomiarów czasu serwera i zastosuj przy generowaniu podpisywanego znacznika czasu. Taka synchronizacja zegara w bocie Binance powinna opierać się na aktualnych, powtarzanych pomiarach. Przechowuj korektę w pamięci lub w kontrolowanej wartości konfiguracyjnej, odświeżaj ją zgodnie z harmonogramem oraz zapisuj w logach zmierzoną różnicę i znacznik czasu użyty w każdym nieudanym żądaniu. Unikaj wpisywania na stałe wartości skopiowanej z jednego testu — opóźnienia sieciowe i warunki pracy hosta mogą się zmieniać.

Zastosuj korektę przed podpisaniem. Znacznik czasu zawarty w podpisywanych parametrach musi być tym samym znacznikiem, który uwzględniono w podpisie; zmiana jego wartości po wygenerowaniu podpisu unieważni podpis. Przetestuj tę kolejność na punkcie końcowym tylko do odczytu, zanim pozwolisz botowi składać zlecenia.

Niewielkie zwiększenie wartości recvWindow może uwzględnić zwykłe opóźnienia sieciowe lub niewielkie wahania czasu. Nie naprawi jednak zegara hosta, który stale wskazuje nieprawidłowy czas. Bardzo szerokie okno może też sprawić, że opóźnione żądania będą akceptowane dłużej, niż zamierzono, dlatego ustaw wartość możliwie niską, z uwzględnieniem zmierzonych opóźnień bota i zasad API.

Stosuj tylko jedną metodę korekty naraz. Jeśli zegar hosta jest zsynchronizowany, a zmierzona różnica wynosi prawie zero, usuń zbędną korektę po stronie aplikacji, zamiast nakładać korektę czasu serwera na korektę stosowaną już przez bibliotekę. Zanim dodasz własny kod, sprawdź, jak biblioteka klienta obsługuje znaczniki czasu.

7. Przetestuj przywrócenie działania i zapobiegaj ponownym rozbieżnościom zegara

Ponownie wyślij to samo podpisane żądanie tylko do odczytu i potwierdź, że odpowiedź nie zawiera już kodu -1021. Porównaj jego znacznik czasu, zmierzoną różnicę względem czasu serwera i opóźnienie w obie strony z wcześniejszym błędem. Dopiero wtedy wznów obsługę zleceń — najlepiej w trybie testowym lub o niskim ryzyku, jeśli Twoja konfiguracja to umożliwia.

Zapisuj w logach nazwę hosta lub węzła, lokalny znacznik czasu, zmierzoną różnicę i kod błędu API. Ustaw alerty dla powtarzających się błędów znacznika czasu, a nie dla pojedynczego incydentu. Seria błędów po ponownym uruchomieniu może oznaczać, że synchronizacja jeszcze się nie zakończyła, a powracające problemy na jednym węźle sugerują usterkę dotyczącą konkretnego hosta.

Sprawdzaj zegar ponownie po wstrzymaniu maszyny wirtualnej, ponownym uruchomieniu, migracji kontenera i restarcie usługi czasu. Jeśli błędy wrócą po zmianie hosta, wstrzymaj składanie zleceń i sprawdź węzeł, który obsłużył żądanie, zanim zwiększysz wartość recvWindow. Taka kontrola może zapobiec temu, by nieaktualny zegar zmienił przejściowy problem infrastruktury w serię odrzuconych zleceń.