Binance error -1021 timestamp: causes and how to fix it

Binance API error -1021 INVALID_TIMESTAMP means the timestamp on your signed request falls outside the window Binance will accept. The message usually reads "Timestamp for this request is outside of the recvWindow" or "was 1000ms ahead of the server's time". In most cases your own clock is the cause, so the fix is to synchronise it, measure the offset against Binance's server time, and handle any remaining network delay properly. A larger recvWindow can hide the problem, but it should not be your first move.

What the error means

Binance requires a timestamp parameter on signed endpoints, meaning requests that touch your account: placing an order or reading balances. It should be the time in milliseconds at which the request was created. Binance uses it to reject stale or replayed requests, so a captured request cannot simply be resent later.

The check is written out in Binance's documentation:

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

Read that as two separate limits, and notice which message goes with which.

• Too far ahead: if your timestamp is 1,000 ms or more ahead of Binance's clock, you get "Timestamp for this request was 1000ms ahead of the server's time". Your clock is running fast.
• Too far behind: if your timestamp is older than recvWindow when Binance processes it, you get "Timestamp for this request is outside of the recvWindow". Your clock is slow, or the request took too long to arrive.

The two limits are not equal. You have 5,000 ms of tolerance on the slow side by default, but only 1,000 ms on the fast side, and raising recvWindow does nothing for the fast side.

Step 1: measure the offset

Do not guess. Fetch the server time and compare it to your own clock. The public endpoint needs no key. For USD-margined futures it is https://fapi.binance.com/fapi/v1/time, and for spot it is https://api.binance.com/api/v3/time.

A small Python check looks like this:

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)

This uses the midpoint of the round trip as your best estimate of when the server read its clock. Run it a few times. A positive offset means Binance's clock is ahead of yours, so your clock is slow. A negative offset means yours is fast. If the round trip is large or varies a lot, your network is part of the problem. Our guide to clock offset explains this method and its limits.

Step 2: synchronise your clock

If the offset is more than a few hundred milliseconds, fix your clock first. That solves most cases.

• Linux: check with timedatectl. Install and enable chrony if no service is synchronising, then use chronyc makestep to correct a large offset at once.
• Windows: open Date and Time settings and use "Sync now". Windows' default synchronisation is infrequent, so a machine can drift between runs. Consider configuring a more frequent time service.
• macOS: turn on "Set time and date automatically" in Date and Time settings.
• Docker: a container uses the host's clock, so fix the host. On Docker Desktop, the internal virtual machine can drift after your laptop sleeps, and restarting it often clears the error.
• Virtual machines and cloud servers: a paused or migrated machine can come back with an old time. Run a time service inside it.

The NTP Pool's documentation describes setting up public time servers if your system does not have a default configured, though most cloud providers offer their own internal time service, which is usually the better choice.

Step 3: generate the timestamp at the right moment

A correct clock can still produce this error if your code creates the timestamp too early. Check for these causes:

• The timestamp is created long before sending. Create it immediately before signing and sending. If your request passes through a queue or a slow thread, the timestamp ages while it waits.
• A retry loop reuses a request. A retried request needs a new timestamp and a new signature, otherwise it will fail with this error after several attempts.
• The wrong unit. Binance expects milliseconds. A timestamp in seconds has ten digits rather than thirteen and will be far outside the window.
• Rate limiting by your own client. A client-side throttle that holds a signed request for several seconds will age it out of the window.
• A heavily loaded machine. When the CPU is saturated, delays between timestamp and send can be surprisingly long.

Step 4: use a time offset in your client if you must

A common approach is to fetch the server time at startup, calculate the difference from your own clock, and add it to every timestamp. Many client libraries offer this as an option, such as one that adjusts for time difference automatically.

This is useful where you cannot control the system clock, but it has a weakness: the offset goes out of date as your clock keeps drifting. If you use this approach, refresh it regularly and handle the error by refreshing once before retrying. Fixing the system clock is the better long-term solution, since all your software benefits from it.

Step 5: think carefully about recvWindow

recvWindow is the number of milliseconds after timestamp that the request stays valid. It defaults to 5,000. Binance's documentation describes it as a way to say that a request must be processed within a certain time or be rejected, which is a safety feature rather than a nuisance. Increasing it may stop the errors, but consider what it means. It tells Binance you are happy for an order created several seconds ago to be executed now. In a fast market, a trade you decided on 30 seconds ago may be a very different trade today.

A large window also masks the real issue, whether that is a drifting clock or an unreliable network. It does not help at all if your clock is fast, because the 1,000 ms limit is separate. Increase it only moderately, only as a stopgap and only once you have measured what is going on. If you find you need a large window, the real problem is elsewhere.

When the problem is the network or Binance

If your clock is correct and timestamps are created at the right moment, look at the path. High latency, packet loss or a congested proxy can make requests take long enough to fall outside the window. The round-trip time from Step 1 will show this. Binance's API also sits behind infrastructure of its own, so short-lived delays are possible at busy times.

Occasional, isolated errors are usually harmless if you handle them by rebuilding and resending the request. A sudden burst across many machines that were previously fine points to the network or the exchange. Compare with our readings for Binance, including its recent clock offset and response times, and check its announcements. Our data shows Binance's public API only as seen from our location, though.

Handling it in code

A robust client treats -1021 as a known, recoverable condition rather than a generic failure.

• Recreate, do not resend. Build a new request with a new timestamp and signature.
• Check before retrying an order. The rejection means this specific request was not processed, but if your earlier attempts had other errors, query the order status first so you do not double up. Use a unique client order ID so a duplicate can be detected.
• Limit retries. Retrying in a tight loop can lead you into rate limits, and our rate limit guide explains the consequences.
• Log the offset and the round trip. When this error recurs, a log tells you at once whether your clock has drifted or the network has worsened.
• Alert on it. A rising rate of -1021 is an early warning that a machine's clock is going wrong.

Do other exchanges have the same error?

Yes. Any exchange using signed requests has some version of this check, under a different code and with a different window. Bybit, for instance, has a timestamp check against its own server time and a recv_window parameter, and OKX requires a timestamp in its request headers. The advice is the same, but read each exchange's documentation for the exact limits.

Common questions about error -1021

Why does it work on my laptop and fail on my server, or the reverse?

Because each machine has its own clock and route to Binance. Run the offset check on both. Cloud servers normally have good time, while laptops that sleep often do not.

Why did the error start suddenly when nothing changed?

Clocks drift slowly. An offset can grow for weeks until it crosses the limit. A system update can also disable a time service, and a change to a new network can raise latency.

Is it safe to set recvWindow to its maximum?

It stops many errors, but it means Binance may execute a request that is far older than you intended, in a market that may have moved. We would treat it as a temporary measure at most.

Fix it in this order

1. Read which of the two messages you received.
2. Measure your offset against Binance's server time.
3. Synchronise your system clock and confirm it stays synchronised.
4. Create the timestamp immediately before signing and sending.
5. Make sure retries rebuild the timestamp and signature.
6. Only then consider a moderate change to recvWindow.

Related reading: Clock offset and stale quotes · Exchange API rate limits and error 429 · Why an exchange API returns 403 or 451

Sources

Binance · Error codes · Binance · General information and timing security · NTP Pool Project · About Tickmark