Lỗi Binance -1021 «Timestamp for this request»: nguyên nhân và cách sửa

Lỗi API Binance -1021 INVALID_TIMESTAMP nghĩa là dấu thời gian trên yêu cầu có chữ ký của bạn nằm ngoài cửa sổ Binance chấp nhận. Thông báo thường là Timestamp for this request is outside of the recvWindow hoặc was 1000ms ahead of the server's time. Đa số trường hợp nguyên nhân là đồng hồ của bạn, nên cách sửa là đồng bộ nó, đo độ lệch với giờ máy chủ Binance và xử lý đúng phần độ trễ mạng còn lại. recvWindow lớn hơn có thể che vấn đề, nhưng không nên là bước đầu tiên.

Lỗi này có nghĩa gì

Binance yêu cầu tham số timestamp trên endpoint có chữ ký, tức các yêu cầu chạm vào tài khoản: đặt lệnh hoặc đọc số dư. Nó phải là thời gian tính bằng mili giây lúc tạo yêu cầu. Binance dùng nó để từ chối yêu cầu cũ hoặc phát lại, để yêu cầu bị bắt không thể gửi lại sau đó.

Phép kiểm tra được viết trong tài liệu Binance:

if (timestamp < serverTime + 1000 && serverTime - timestamp <= recvWindow) { process } else { reject }

Hãy đọc đó là hai giới hạn riêng, và chú ý thông báo nào đi với giới hạn nào.

• Đi trước quá xa: nếu dấu thời gian đi trước đồng hồ Binance từ 1.000 ms trở lên, bạn nhận Timestamp for this request was 1000ms ahead of the server's time. Đồng hồ của bạn chạy nhanh.
• Đi sau quá xa: nếu dấu thời gian cũ hơn recvWindow khi Binance xử lý, bạn nhận Timestamp for this request is outside of the recvWindow. Đồng hồ của bạn chậm, hoặc yêu cầu đến quá lâu.

Hai giới hạn không bằng nhau. Bạn có dung sai 5.000 ms phía chậm theo mặc định, nhưng chỉ 1.000 ms phía nhanh, và tăng recvWindow không có tác dụng gì với phía nhanh.

Bước 1: đo độ lệch

Đừng đoán. Lấy giờ máy chủ và so với đồng hồ của bạn. Endpoint công khai này không cần khóa. Với hợp đồng tương lai ký quỹ USD là https://fapi.binance.com/fapi/v1/time, với giao ngay là https://api.binance.com/api/v3/time.

Một kiểm tra Python nhỏ như sau:

import time, requests; t0 = time.time()*1000; s = requests.get("https://fapi.binance.com/fapi/v1/time").json()["serverTime"]; t1 = time.time()*1000; print("offset ms:", s - (t0 + t1) / 2, "round trip ms:", t1 - t0)

Cách này dùng trung điểm khứ hồi làm ước tính tốt nhất cho lúc máy chủ đọc đồng hồ. Chạy vài lần. Độ lệch dương nghĩa là đồng hồ Binance đi trước, tức đồng hồ của bạn chậm. Độ lệch âm nghĩa là đồng hồ của bạn nhanh. Nếu khứ hồi lớn hoặc dao động nhiều, mạng của bạn là một phần vấn đề. Hướng dẫn lệch đồng hồ giải thích phương pháp và giới hạn của nó.

Bước 2: đồng bộ đồng hồ

Nếu độ lệch hơn vài trăm mili giây, hãy sửa đồng hồ trước. Việc này giải quyết đa số trường hợp.

• Linux: kiểm tra bằng timedatectl. Cài và bật chrony nếu chưa có dịch vụ đồng bộ, rồi dùng chronyc makestep để chỉnh độ lệch lớn ngay.
• Windows: mở cài đặt Ngày và Giờ và dùng «Sync now». Đồng bộ mặc định của Windows thưa, nên máy có thể trôi giữa các lần. Hãy cân nhắc dịch vụ thời gian thường xuyên hơn.
• macOS: bật «Đặt ngày và giờ tự động» trong cài đặt Ngày và Giờ.
• Docker: container dùng đồng hồ của máy chủ, nên hãy sửa máy chủ. Trên Docker Desktop, máy ảo bên trong có thể trôi sau khi laptop ngủ, và khởi động lại thường hết lỗi.
• Máy ảo và máy chủ đám mây: máy bị tạm dừng hoặc di chuyển có thể quay lại với giờ cũ. Hãy chạy dịch vụ thời gian bên trong.

Tài liệu NTP Pool mô tả cách thiết lập máy chủ thời gian công cộng nếu hệ thống chưa cấu hình, dù hầu hết nhà cung cấp đám mây có dịch vụ thời gian nội bộ, thường là lựa chọn tốt hơn.

Bước 3: tạo dấu thời gian đúng lúc

Đồng hồ đúng vẫn có thể gây lỗi này nếu mã tạo dấu thời gian quá sớm. Hãy kiểm tra các nguyên nhân sau:

• Dấu thời gian tạo lâu trước khi gửi. Hãy tạo ngay trước khi ký và gửi. Nếu yêu cầu đi qua hàng đợi hoặc luồng chậm, dấu thời gian già đi khi đợi.
• Vòng thử lại dùng lại yêu cầu. Yêu cầu thử lại cần dấu thời gian và chữ ký mới, nếu không sẽ lỗi này sau vài lần.
• Sai đơn vị. Binance cần mili giây. Dấu thời gian tính bằng giây có mười chữ số thay vì mười ba và nằm xa ngoài cửa sổ.
• Giới hạn tần suất của chính ứng dụng. Bộ giới hạn phía client giữ yêu cầu đã ký vài giây sẽ làm nó già ra khỏi cửa sổ.
• Máy quá tải. Khi CPU bão hòa, độ trễ giữa dấu thời gian và gửi có thể dài bất ngờ.

Bước 4: dùng độ lệch trong client nếu cần

Cách phổ biến là lấy giờ máy chủ khi khởi động, tính chênh với đồng hồ của bạn và cộng vào mọi dấu thời gian. Nhiều thư viện client có tùy chọn này, như tùy chọn tự điều chỉnh chênh thời gian.

Cách này hữu ích khi bạn không kiểm soát được đồng hồ hệ thống, nhưng có điểm yếu: độ lệch lỗi thời khi đồng hồ tiếp tục trôi. Nếu dùng, hãy làm mới định kỳ và xử lý lỗi bằng cách làm mới một lần trước khi thử lại. Sửa đồng hồ hệ thống là giải pháp dài hạn tốt hơn, vì mọi phần mềm đều được lợi.

Bước 5: cân nhắc kỹ recvWindow

recvWindow là số mili giây sau timestamp mà yêu cầu còn hiệu lực. Mặc định là 5.000. Tài liệu Binance mô tả nó như cách nói yêu cầu phải được xử lý trong một thời gian nhất định hoặc bị từ chối, tức tính năng an toàn chứ không phải phiền toái. Tăng nó có thể hết lỗi, nhưng hãy nghĩ ý nghĩa. Bạn đang nói với Binance rằng bạn chấp nhận lệnh tạo vài giây trước được thực thi bây giờ. Trong thị trường nhanh, giao dịch bạn quyết định 30 giây trước có thể đã là giao dịch rất khác.

Cửa sổ lớn cũng che vấn đề thật, dù là đồng hồ trôi hay mạng không ổn định. Nó không giúp gì nếu đồng hồ nhanh, vì giới hạn 1.000 ms là riêng. Chỉ tăng vừa phải, chỉ như biện pháp tạm thời và chỉ sau khi đã đo. Nếu thấy cần cửa sổ lớn, vấn đề thật nằm ở chỗ khác.

Khi vấn đề là mạng hoặc Binance

Nếu đồng hồ đúng và dấu thời gian tạo đúng lúc, hãy xem đường đi. Độ trễ cao, mất gói hoặc proxy nghẽn có thể làm yêu cầu đủ lâu để rơi ngoài cửa sổ. Thời gian khứ hồi ở Bước 1 sẽ cho thấy điều này. API của Binance cũng nằm sau hạ tầng riêng, nên độ trễ ngắn có thể xảy ra lúc bận.

Lỗi đơn lẻ thỉnh thoảng thường vô hại nếu xử lý bằng cách dựng lại và gửi lại yêu cầu. Đợt bùng phát đột ngột trên nhiều máy vốn ổn cho thấy vấn đề ở mạng hoặc sàn. Hãy so với số đọc của chúng tôi về Binance, gồm độ lệch đồng hồ và thời gian phản hồi gần đây, và xem thông báo của sàn. Tuy vậy dữ liệu của chúng tôi chỉ cho thấy API công khai của Binance nhìn từ vị trí của chúng tôi.

Xử lý trong mã

Client tốt coi -1021 là tình huống đã biết và phục hồi được, không phải lỗi chung.

• Tạo lại, đừng gửi lại. Dựng yêu cầu mới với dấu thời gian và chữ ký mới.
• Kiểm tra trước khi thử lại lệnh. Từ chối nghĩa là yêu cầu này chưa được xử lý, nhưng nếu các lần trước có lỗi khác, hãy truy vấn trạng thái lệnh trước để tránh gấp đôi. Dùng mã lệnh client duy nhất để phát hiện trùng.
• Giới hạn số lần thử lại. Thử lại trong vòng lặp chặt có thể dẫn đến giới hạn tần suất, và hướng dẫn giới hạn tần suất giải thích hậu quả.
• Ghi độ lệch và khứ hồi. Khi lỗi này lặp lại, nhật ký cho biết ngay đồng hồ trôi hay mạng xấu đi.
• Đặt cảnh báo. Tỷ lệ -1021 tăng là cảnh báo sớm đồng hồ máy đang có vấn đề.

Các sàn khác có lỗi tương tự không?

Có. Sàn nào dùng yêu cầu có chữ ký đều có một phiên bản của kiểm tra này, với mã và cửa sổ khác. Ví dụ Bybit kiểm tra dấu thời gian theo giờ máy chủ và có tham số recv_window, còn OKX yêu cầu dấu thời gian trong header. Lời khuyên giống nhau, nhưng hãy đọc tài liệu từng sàn để biết giới hạn chính xác.

Câu hỏi thường gặp về lỗi -1021

Vì sao chạy được trên laptop mà lỗi trên máy chủ, hoặc ngược lại?

Vì mỗi máy có đồng hồ và đường đến Binance riêng. Hãy chạy kiểm tra độ lệch trên cả hai. Máy chủ đám mây thường có giờ tốt, còn laptop hay ngủ thường không.

Vì sao lỗi đột ngột xuất hiện khi không đổi gì?

Đồng hồ trôi chậm. Độ lệch có thể tăng nhiều tuần cho đến khi vượt giới hạn. Bản cập nhật hệ thống cũng có thể tắt dịch vụ thời gian, và đổi mạng có thể tăng độ trễ.

Đặt recvWindow tối đa có an toàn không?

Nó chặn nhiều lỗi, nhưng nghĩa là Binance có thể thực thi yêu cầu cũ hơn nhiều so với ý định, trong thị trường có thể đã thay đổi. Chúng tôi chỉ coi đó là biện pháp tạm thời.

Sửa theo thứ tự này

1. Đọc xem bạn nhận thông báo nào trong hai thông báo.
2. Đo độ lệch so với giờ máy chủ Binance.
3. Đồng bộ đồng hồ hệ thống và xác nhận nó giữ đồng bộ.
4. Tạo dấu thời gian ngay trước khi ký và gửi.
5. Đảm bảo thử lại sẽ dựng lại dấu thời gian và chữ ký.
6. Chỉ sau đó mới cân nhắc thay đổi vừa phải recvWindow.

Đọc thêm: Lệch đồng hồ và báo giá cũ · Giới hạn tần suất API sàn và lỗi 429 · Vì sao API sàn trả về 403 hoặc 451

Nguồn

Binance · Mã lỗi · Binance · Thông tin chung và an toàn thời gian · NTP Pool Project · Về Tickmark