幣安 API 錯誤 -1021Timestamp for this request：原因和修復方法

幣安 API 錯誤 -1021 INVALID_TIMESTAMP 表示你的簽名請求上的時間戳落在幣安接受的視窗之外。訊息通常是Timestamp for this request is outside of the recvWindow或was 1000ms ahead of the server's time。大多數情況下原因是你自己的時鐘，所以解決辦法是同步時鐘、測量和幣安伺服器時間的偏移，並妥善處理剩餘的網路延遲。調大 recvWindow 可以掩蓋問題，但不應該是第一步。

這個錯誤是什麼意思

幣安要求籤名介面（也就是涉及你賬戶的請求，如下單或查詢餘額）帶上 timestamp 引數，它應該是請求建立時的毫秒時間。幣安用它拒絕過期或重放的請求，這樣被截獲的請求不能之後再發一次。

幣安的文件寫明瞭這項檢查：

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

這是兩個獨立的限制，請注意每條訊息對應哪個。

• 超前太多：如果你的時間戳比幣安時鐘超前 1,000 ms 或以上，會收到Timestamp for this request was 1000ms ahead of the server's time。你的時鐘快了。
• 落後太多：如果幣安處理時你的時間戳已比 recvWindow 還舊，會收到Timestamp for this request is outside of the recvWindow。你的時鐘慢了，或者請求到達得太慢。

兩個限制並不對稱。慢的一側預設有 5,000 ms 容忍度，快的一側只有 1,000 ms，而調大 recvWindow 對快的一側沒有任何作用。

第一步：測量偏移

不要猜。獲取伺服器時間，和自己的時鐘比較。這個公開介面不需要金鑰。U 本位合約是 https://fapi.binance.com/fapi/v1/time，現貨是 https://api.binance.com/api/v3/time。

一個簡單的 Python 檢查如下：

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)

它用往返的中點作為伺服器讀取時鐘時刻的最佳估計。多執行幾次。偏移為正表示幣安時鐘比你的快，也就是你的時鐘慢了；偏移為負表示你的時鐘快了。如果往返時間很大或波動很大，你的網路也是問題的一部分。時鐘偏移指南講了這個方法及其侷限。

第二步：同步時鐘

如果偏移超過幾百毫秒，先修時鐘。這能解決大多數情況。

• Linux：用 timedatectl 檢視。如果沒有服務在同步，安裝並啟用 chrony，然後用 chronyc makestep 立即校正大偏移。
• Windows：開啟日期和時間設定，點選「立即同步」。Windows 預設同步頻率很低，機器在兩次同步之間可能漂移，可以考慮配置更頻繁的時間服務。
• macOS：在日期與時間設定中開啟「自動設定日期和時間」。
• Docker：容器使用宿主機的時鐘，所以要修宿主機。在 Docker Desktop 上，筆記本休眠後內部虛擬機器可能漂移，重啟它常常能解決這個錯誤。
• 虛擬機器和雲伺服器：暫停或遷移過的機器可能帶著舊時間回來。請在裡面執行時間服務。

如果系統沒有預設配置，NTP Pool 的文件說明了如何設定公共時間伺服器，不過大多數雲服務商都提供內部時間服務，通常是更好的選擇。

第三步：在正確的時刻生成時間戳

時鐘正確時，如果程式碼過早建立時間戳，仍可能出現這個錯誤。檢查這些原因：

• 時間戳早在傳送之前就建立了。應該在簽名和傳送之前才建立。如果請求要經過佇列或慢執行緒，時間戳會在等待中變舊。
• 重試迴圈複用了請求。重試的請求需要新的時間戳和新的簽名，否則幾次嘗試後就會因這個錯誤失敗。
• 單位錯誤。幣安要求毫秒。秒級時間戳只有十位而不是十三位，會遠遠超出視窗。
• 客戶端自己的限流。客戶端限流器把已簽名的請求扣留幾秒，會讓它超出視窗。
• 機器負載過高。CPU 飽和時，從生成時間戳到傳送的延遲可能長得驚人。

第四步：必要時在客戶端使用時間偏移

常見做法是啟動時獲取伺服器時間，算出和自己時鐘的差，然後加到每個時間戳上。很多客戶端庫提供這個選項，比如自動調整時間差。

當你無法控制系統時鐘時這很有用，但它有個弱點：隨著時鐘繼續漂移，偏移會過時。如果用這種辦法，請定期重新整理，並在遇到這個錯誤時先重新整理一次再重試。修好系統時鐘是更好的長期方案，因為所有軟體都能受益。

第五步：謹慎對待 recvWindow

recvWindow 是 timestamp 之後請求保持有效的毫秒數，預設 5,000。幣安文件把它描述為一種宣告：請求必須在一定時間內處理，否則被拒絕，這是安全功能，不是麻煩。調大可能讓錯誤消失，但要想想這意味著什麼。它等於告訴幣安，你願意讓幾秒前建立的訂單現在才執行。快速行情中，30 秒前決定的交易現在可能完全是另一筆交易。

大視窗還會掩蓋真正的問題，無論是時鐘漂移還是網路不穩定。如果你的時鐘快了，它也完全幫不上忙，因為 1,000 ms 的限制是獨立的。只能適度調大，只作為臨時措施，並且只在測量清楚之後。如果發現需要很大的視窗，真正的問題在別處。

問題在網路或幣安時

如果時鐘正確、時間戳也在正確時刻建立，就看路徑。高延遲、丟包或擁塞的代理都可能讓請求耗時過長而超出視窗。第一步的往返時間能顯示這一點。幣安的 API 也有自己的基礎設施，繁忙時可能出現短暫延遲。

偶發的孤立錯誤通常無害，重建請求再發即可。之前都正常的多臺機器突然同時大量報錯，說明問題在網路或交易所。可以對比我們對幣安的讀數，包括最近的時鐘偏移和響應時間，並檢視公告。不過我們的資料只是從我們的地點看幣安的公開 API。

在程式碼中處理

健壯的客戶端把 -1021 當作已知的、可恢復的情況，而不是一般失敗。

• 重建，不要重發。用新的時間戳和簽名構建新請求。
• 重試下單前先檢查。這個拒絕說明這次請求沒有被處理，但如果之前的嘗試有其他錯誤，先查詢訂單狀態，以免重複。使用唯一的客戶端訂單號，方便發現重複。
• 限制重試次數。緊密迴圈重試可能觸發頻率限制，頻率限制指南講了後果。
• 記錄偏移和往返時間。錯誤再次出現時，日誌能立刻告訴你是時鐘漂移了還是網路變差了。
• 設定告警。-1021 比例上升是機器時鐘出問題的早期訊號。

其他交易所也有同樣的錯誤嗎？

有。任何使用簽名請求的交易所都有類似檢查，只是錯誤碼和視窗不同。例如 Bybit 會根據自己的伺服器時間檢查時間戳，並有 recv_window 引數；OKX 要求在請求頭中帶時間戳。建議是一樣的，但具體限制請讀各交易所的文件。

關於 -1021 錯誤的常見問題

為什麼在筆記本上正常、在伺服器上失敗，或者反過來？

因為每臺機器有自己的時鐘和到幣安的路徑。在兩臺機器上都執行偏移檢查。雲伺服器的時間通常很好，而經常休眠的筆記本往往不行。

什麼都沒改，為什麼突然開始報錯？

時鐘漂移很慢，偏移可能增長几周才超過限制。系統更新也可能停用時間服務，換網路可能提高延遲。

把 recvWindow 設成最大安全嗎？

它能消除很多錯誤，但也意味著幣安可能執行一個比你預期舊得多的請求，而市場可能已經變了。我們最多把它當作臨時措施。

按這個順序修復

1. 看清你收到的是兩條訊息中的哪一條。
2. 測量和幣安伺服器時間的偏移。
3. 同步系統時鐘，並確認它保持同步。
4. 在簽名和傳送之前才建立時間戳。
5. 確保重試時重建時間戳和簽名。
6. 最後才考慮適度調整 recvWindow。

相關閱讀：時鐘偏移與過時報價 · 交易所 API 頻率限制和 429 錯誤 · 交易所 API 為什麼返回 403 或 451

來源

幣安 · 錯誤碼 · 幣安 · 基本資訊和時間安全 · NTP Pool Project · 關於 Tickmark