바이낸스 recvWindow 뜻 2026｜timestamp·시간 오차·-1021 오류

바이낸스 recvWindow 뜻 2026｜timestamp·시간 오차·-1021 오류

바이낸스 recvWindow는 서명된 API 요청이 timestamp 이후 얼마 동안 유효한지 정하는 시간 범위입니다. 주문을 얼마나 오래 미체결 상태로 둘 것인지 정하는 옵션이 아니며, 주문 체결을 기다리는 시간이나 HTTP 응답 대기 시간과도 다릅니다.

API 호출 예산이 충분하고 잔고도 있는데 요청이 시간 오류로 거절될 수 있습니다. 컴퓨터 시계가 서버와 어긋나 있거나, 요청을 만든 뒤 전송하기까지 오래 기다렸거나, 시간 단위를 잘못 처리한 경우를 따로 확인해야 합니다. recvWindow를 크게 바꾸는 것만으로 이 문제들이 모두 해결되지는 않습니다.

이 글은 Binance Spot REST API의 Timing Security를 기준으로 설명합니다. 2026년 10월 27일 공식 개발 문서에서 확인한 범위이며, 다른 제품의 동일한 이름을 가진 옵션까지 같은 규칙으로 단정하지 않습니다. 아래 사례의 시각과 지연은 이해를 위한 가정입니다.

핵심 개념부터 구분하기

recvWindow를 5초로 설정했다고 주문이 5초 뒤 취소되는 것은 아닙니다. 반대로 HTTP 요청을 30초 동안 기다리도록 설정했다고 서버가 오래된 timestamp를 30초 동안 받아주는 것도 아닙니다. 전송 요청의 유효성, 통신 응답 대기, 주문의 생명주기를 분리해 읽어야 합니다.

1. 왜 요청에 시간이 필요한가

서명은 요청 내용과 인증 정보를 연결하는 역할을 합니다. 그러나 과거에 만들어진 요청이 언제까지나 유효하다면 시간에 민감한 작업을 관리하기 어렵습니다. Timing Security는 요청에 담긴 시각과 서버의 시각을 비교하는 별도 검증입니다.

가격과 잔고가 바뀌는 환경에서는 오래 전에 만들어진 거래 의사가 뒤늦게 전송되는 상황도 고려해야 합니다. recvWindow는 이런 요청의 시간 범위를 제한하는 요소입니다. 다만 이것만으로 가격 위험이나 중복 주문, 잘못된 매매 전략이 모두 방지되는 것은 아닙니다.

시스템을 이해할 때는 검사를 여러 층으로 나누면 쉽습니다. 인증·서명, 시간 유효성, 권한, 주문 필터, 잔고, 거래 상태 등이 서로 다른 이유로 실패할 수 있습니다. 한 검사를 통과했다는 사실을 전체 주문 성공으로 확대해서 해석하지 않습니다.

일반 앱 사용자와 API 사용자의 차이

일반 거래 화면을 사용하는 사람은 recvWindow라는 입력칸을 직접 보지 않을 수 있습니다. 이 글은 개발자가 API 요청을 구성하거나 외부 거래 도구의 오류를 분석할 때 필요한 설명입니다. 현재 앱 화면에 해당 설정 메뉴가 있다고 가정해서 안내하지 않습니다.

외부 도구를 사용하는 경우에는 그 도구가 어느 API를 사용하고 시간을 어떻게 맞추는지 확인해야 합니다. 사용자가 임의로 PC 시각을 몇 초 늦추는 방식은 다른 프로그램에 문제를 줄 수 있습니다. 공식 시간 동기화와 도구의 진단 절차를 우선하는 편이 낫습니다.

2. 공식 수치와 단위

Spot REST API 공식 문서의 Timing Security는 recvWindow를 보내지 않으면 기본 5,000밀리초, 최대 60,000밀리초라고 안내합니다. 문서는 5,000 이하의 작은 값을 권장합니다. 최대값을 모든 상황의 권장 설정으로 읽지 마세요.

recvWindow의 단위는 밀리초입니다. 현재 문서는 소수점 이하 세 자리까지 지원한다고 설명하며, 예를 들어 6000.346은 밀리초 단위 숫자의 소수 정밀도를 나타냅니다. timestamp가 마이크로초를 지원한다는 사실과 recvWindow 숫자의 기본 단위를 혼동하면 안 됩니다.

timestamp는 현재 시각을 나타내며 밀리초 또는 마이크로초로 전달할 수 있다고 공식 문서에 설명되어 있습니다. 기존 코드가 밀리초를 쓰고 있다면 일부 모듈만 마이크로초로 바꾸지 않도록 주의해야 합니다. 입력 단위, 저장 단위, 비교 단위를 모두 확인하는 것이 중요합니다.

초·밀리초·마이크로초 비교

숫자의 자릿수만 보고 변환하는 임시 처리는 예외를 만들 수 있습니다. 시간 값을 만드는 함수와 직렬화하는 함수가 어떤 단위를 계약으로 사용하는지 명시하는 편이 낫습니다. 값에 “ms”처럼 단위를 표시하는 내부 변수 이름도 오류를 찾는 데 도움이 됩니다.

3. 서버가 시간을 비교하는 방식

공식 문서는 요청 timestamp가 서버 시각보다 1초 이상 앞서지 않는지 확인하고, 서버 시각에서 timestamp를 뺀 값이 recvWindow 안에 있는지 확인하는 흐름을 제시합니다. 요청 처리 중 다시 현재 시각을 구해 Matching Engine으로 전달하기 전에 한 번 더 시간 범위를 확인합니다.

따라서 처음 도착한 순간에 범위 안이었다는 사실만으로 모든 후속 검사를 보장할 수 없습니다. 요청 생성·서명·전송·네트워크 이동·서버 처리 사이의 시간이 전체 결과에 영향을 줄 수 있습니다. 이것은 공식 검증 흐름에 대한 설명이지 내부 지연 시간을 예측하는 공식이 아닙니다.

앞선 시계와 뒤처진 시계의 문제도 다릅니다. recvWindow를 늘리는 것은 오래된 요청을 허용하는 범위와 관련되지만, 미래 쪽으로 너무 앞선 timestamp를 정상으로 만드는 만능 스위치는 아닙니다. 컴퓨터 시계가 서버보다 앞서 있다는 메시지가 나오면 시간 동기화부터 확인해야 합니다.

시간 오차와 전송 지연은 따로 측정

내 시계가 서버와 얼마나 어긋났는지와 요청이 네트워크에서 얼마나 걸렸는지는 같은 값이 아닙니다. 네트워크 왕복 시간을 그대로 시계 오차로 더하면 오히려 보정이 틀어질 수 있습니다. 서버 시간 조회에는 요청과 응답 이동 시간도 포함된다는 점을 고려해야 합니다.

운영 구현에서는 여러 관측값과 왕복 지연을 비교해 보정 품질을 평가할 수 있습니다. 이때 보정 알고리즘은 클라이언트의 설계이며 Binance가 모든 환경에 특정 공식을 보장한다는 뜻은 아닙니다. 지연 변동이 큰 표본 하나만으로 시스템 전체 시계를 바꾸지 마세요.

4. -1021과 -1022를 구분하기

공식 오류 문서는 -1021 INVALID_TIMESTAMP를 요청 시간이 recvWindow 밖이거나 서버보다 앞선 경우와 연결합니다. -1022 INVALID_SIGNATURE는 서명이 유효하지 않은 경우입니다. 두 오류는 이름도 원인도 다릅니다.

시간 오류를 해결하려고 API Secret을 계속 재발급하는 것은 진단 순서를 흐릴 수 있습니다. 반대로 서명할 때 사용한 문자열과 실제 전송 문자열이 다르다면 시계만 맞춰도 해결되지 않습니다. 오류 코드, 메시지, 요청 생성 과정의 어느 단계가 바뀌었는지 분리해서 확인합니다.

timestamp나 recvWindow가 서명 대상 파라미터에 포함된 상태에서 값을 바꾸면 서명도 다시 계산해야 합니다. 이미 서명한 요청의 timestamp만 나중에 수정해서 전송하면 다른 종류의 문제가 생길 수 있습니다. 파라미터 확정과 서명 생성의 순서를 명확히 해야 합니다.

비밀값 없이 남길 진단 기록

요청을 만든 시각, 실제 전송 시각, 응답을 받은 시각, 사용하는 시간 단위, recvWindow 값, 오류 코드는 유용한 기록입니다. 전체 인증 헤더나 Secret을 기록할 필요는 없습니다. 서명 원문에 민감한 파라미터가 있다면 외부 공유 전에 제거해야 합니다.

로그가 “주문 실패” 한 줄뿐이면 원인을 복원하기 어렵습니다. 시간 오류인지 네트워크 대기 초과인지 서버 처리 결과가 불명확한지 분류할 수 있어야 합니다. 반대로 모든 인증 정보를 그대로 저장하는 것은 진단의 편의보다 노출 위험을 크게 만들 수 있습니다.

5. 실무 확인 절차

1단계: 오류를 있는 그대로 분류

먼저 실제 응답의 코드와 메시지를 확인합니다. -1021인지, -1022인지, 클라이언트 timeout인지, API의 처리 시간 초과 응답인지 구분합니다. “오래 걸렸다”는 느낌만으로 recvWindow 문제라고 판단하지 않습니다.

통신이 끊겨 응답을 전혀 받지 못한 경우에는 서버가 주문을 받아들였는지 알 수 없을 수 있습니다. 이 상황에서 새로운 timestamp로 같은 주문을 바로 보내면 중복 의사가 실행될 가능성을 따로 고려해야 합니다. 시간 검증 오류와 결과 불명확 상황을 같은 재시도 규칙으로 묶지 마세요.

2단계: 시스템 시간 상태 확인

운영체제의 시간 동기화가 정상인지 확인합니다. 가상 머신, 컨테이너, 호스트의 시간 관계도 점검할 수 있습니다. 개발용 노트북에서는 절전 복귀나 네트워크 변경 이후 문제가 생기는지 관찰해 볼 수 있지만, 실제 원인은 로그로 확인해야 합니다.

시간대 표시와 절대 시각은 다릅니다. 화면이 한국시간으로 보이는지 UTC로 보이는지보다 API에 전달되는 타임스탬프가 정확한지가 중요합니다. 화면에 9시간 차이가 보인다는 이유만으로 timestamp에 9시간을 더하는 조치를 해서는 안 됩니다.

3단계: 서버 시간과 비교

Spot REST의 GET /api/v3/time은 서버 시각을 확인하는 공식 경로입니다. 현재 사용하는 제품과 환경이 맞는지 확인한 뒤 비교합니다. 테스트 환경의 시간·주소와 운영 환경의 요청을 뒤섞지 않도록 구분하세요.

한 번의 조회가 느렸다면 그 표본의 품질이 낮을 수 있습니다. 왕복 지연과 반복 관측을 고려해 시간 보정이 안정적인지 확인합니다. 지나치게 자주 서버 시간을 조회하면 호출 예산을 소모하므로, 시간 동기화 주기도 Request Weight 관리와 함께 설계해야 합니다.

4단계: timestamp를 만드는 위치 확인

주문 의사를 만든 즉시 timestamp를 넣고 긴 작업 큐에 보관하면 전송 시점에는 값이 오래될 수 있습니다. 거래 의사와 전송 요청을 구분하고, 실제 전송에 가까운 시점에 적절한 현재 시각으로 서명하는 구조를 검토합니다.

그렇다고 오래된 거래 의사를 새 timestamp로 바꾸기만 하면 되는 것은 아닙니다. 가격·잔고·전략 조건이 이미 달라졌을 수 있으므로, 큐에서 꺼낸 작업을 여전히 실행할지 별도로 판단해야 합니다. 통신 유효성을 갱신하는 것과 거래 판단이 최신이라는 것은 다릅니다.

5단계: 서명 이후 변경 여부 확인

파라미터를 확정하고 직렬화한 내용과 실제 보내는 내용이 일치하는지 점검합니다. timestamp를 다시 넣는 미들웨어, 숫자 형식을 바꾸는 라이브러리, 요청 재사용 기능이 있는지 확인할 수 있습니다. 전체 구조를 바꾸기 전에 어느 단계에서 값이 달라지는지 관찰하는 편이 좋습니다.

예를 들어 재시도 모듈이 timestamp만 최신으로 바꾸고 서명을 재사용하면 시간 오류가 사라지는 대신 서명 오류가 나타날 수 있습니다. 이런 경우 recvWindow를 더 늘리는 조치는 문제와 직접 관련이 없습니다. 데이터 생성과 서명을 하나의 일관된 과정으로 다룹니다.

6. 다섯 가지 상황별 예시

다음 사례는 원리를 설명하기 위한 가상 상황입니다. 특정 네트워크 지연이나 설정값을 추천하는 거래 지침이 아니며, 실제 서비스 결과는 현재 요청과 공식 규칙으로 확인해야 합니다.

예시 1: 밀리초 대신 초를 넣은 요청

프로그램의 시간 함수가 초 단위 값을 반환하는데 이를 밀리초 기준으로 사용하는 코드에 그대로 전달했다고 가정합니다. 숫자는 정상적인 정수처럼 보이지만 서버가 해석하는 시각은 현재와 크게 달라질 수 있습니다. 이런 문제는 recvWindow를 조금 늘려 해결할 성격이 아닙니다.

시간 함수의 반환 단위와 API 파라미터 규격을 먼저 맞춥니다. 변환은 한 곳에서 명확히 수행하고, 여러 모듈에서 중복 변환하지 않도록 점검하세요. 로그에는 변환 전후 값을 무작정 쌓기보다 단위를 명시한 진단 항목을 남기면 원인 확인이 쉬워집니다.

예시 2: 시계가 서버보다 앞선 경우

컴퓨터 시계가 실제보다 앞서 있어 timestamp가 미래 쪽으로 치우친 상황을 생각해 볼 수 있습니다. 공식 오류 메시지가 서버보다 앞선 요청이라고 알려준다면, 오래된 요청 허용 범위를 넓히는 것보다 시계 오차를 해결하는 것이 먼저입니다.

이때 PC의 시각을 임의로 몇 초 늦추는 임시 조치는 다른 프로그램에 영향을 줄 수 있습니다. 정상적인 시간 동기화 상태와 애플리케이션 보정값을 확인하세요. 보정값이 중복 적용되거나 부호가 뒤집힌 경우도 코드와 로그를 대조해 찾을 수 있습니다.

예시 3: 큐에서 오래 기다린 요청

요청을 만들 때 timestamp를 기록하고, 다른 작업 때문에 8초 뒤 전송했다고 가정합니다. recvWindow가 5초라면 전송 전에 이미 요청이 오래된 상태일 수 있습니다. 인터넷 속도가 빠르더라도 애플리케이션 내부 대기가 원인이 될 수 있다는 점이 핵심입니다.

해결 방향은 네트워크만 점검하는 것이 아니라 큐 대기와 서명 시점을 관찰하는 것입니다. 전송 직전에 요청을 구성하더라도 거래 의사 자체가 오래됐다면 재평가가 필요합니다. “시간 검사를 통과시키는 것”과 “적절한 주문을 보내는 것”은 서로 다른 목표입니다.

예시 4: 응답 대기 초과 뒤 재전송

클라이언트가 응답을 받지 못해 timeout을 기록했지만 서버에서는 주문을 처리했을 가능성이 남아 있다고 가정합니다. timestamp를 새로 만들면 요청 시간은 최신이 되지만 원래 주문의 존재 여부는 해결되지 않습니다. 바로 새 주문을 보내면 거래 의사가 두 번 실행될 수 있습니다.

이 경우 원래 clientOrderId와 주문 상태를 확인하는 복구 흐름이 필요합니다. 연결 오류를 모두 “미접수”로 기록하지 말고 결과 불명확 상태를 따로 둡니다. 공식 문서도 처리 시간 초과가 Matching Engine에서의 실패를 항상 의미하지 않는다고 설명합니다.

예시 5: 소수 정밀도를 다른 단위로 해석

recvWindow에 소수점이 들어갈 수 있다는 설명을 보고 값을 마이크로초 정수처럼 바꾸는 실수를 생각해 볼 수 있습니다. 공식 설명은 밀리초 단위를 유지하면서 소수 정밀도를 지원한다는 뜻입니다. 값의 표현 정밀도와 기본 단위는 구별해야 합니다.

사용 중인 라이브러리가 소수값을 어떻게 직렬화하는지 확인하고, 필요하지 않은 정밀도를 억지로 도입하지 않습니다. 값이 문자열인지 숫자인지, 서명할 때와 전송할 때 같은 표현이 유지되는지도 점검하세요. 기능 지원이 있다는 사실이 복잡한 표현을 반드시 사용해야 한다는 뜻은 아닙니다.

7. recvWindow를 크게 설정하면 좋은가

최대 허용값은 시스템이 받아들일 수 있는 범위의 상한이지 모든 프로그램의 최적값이 아닙니다. 공식 문서가 작은 recvWindow를 권장한다는 점을 먼저 기억해야 합니다. 지연 문제를 가리기 위해 항상 최대값을 넣으면 원인을 파악하기 어려워질 수 있습니다.

큰 값은 오래된 요청을 받아들일 수 있는 시간 범위를 넓힙니다. 시간 검증 실패가 줄었다고 해서 전송 구조나 시계가 정확해졌다고 말할 수는 없습니다. 따라서 변경 전후에 오류율뿐 아니라 요청 생성부터 전송까지 걸린 시간도 관찰해야 합니다.

너무 작은 값을 근거 없이 적용하는 것도 좋지 않습니다. 정상적인 네트워크 변동에도 요청이 자주 거절될 수 있기 때문입니다. 문서 권장 범위, 실제 지연 관측, 사용하는 제품의 조건을 바탕으로 판단하되 이 글의 예시 숫자를 개인 환경의 정답으로 복사하지 마세요.

설정값보다 먼저 볼 세 가지

첫째는 시스템 시계가 정상적으로 동기화되는지입니다. 둘째는 요청이 애플리케이션 안에서 얼마나 기다리는지입니다. 셋째는 실패 시 재시도가 원래 거래 의사를 중복 실행하지 않는지입니다. recvWindow는 이 세 가지를 대신하는 기능이 아닙니다.

오류가 일정 시간에 집중된다면 배치 작업, 절전 복귀, 서버 부하 같은 조건과 함께 관찰할 수 있습니다. 원인을 확정하기 전에는 “Binance가 불안정해서” 또는 “인터넷이 느려서”라고 단정하지 않습니다. 같은 증상도 여러 단계에서 발생할 수 있습니다.

8. 주문 유효기간과의 비교

GTC, IOC, FOK 같은 timeInForce는 주문 실행 조건과 관련됩니다. recvWindow는 요청이 시간상 받아들여질 수 있는지의 검사입니다. 두 항목은 이름에 시간 의미가 들어가지만 작동하는 단계가 다릅니다.

GTC 주문을 recvWindow 5,000으로 전송해 정상 접수했다고 해서 5초 뒤 주문이 사라지는 것은 아닙니다. 이후 주문 유지와 체결은 주문 종류·조건·거래소 규칙에 따릅니다. 반대로 긴 주문 유효기간을 선택해도 API 요청의 timestamp가 오래되면 접수 단계에서 거절될 수 있습니다.

POV Order Expiry나 TWAP의 실행 시간도 별도 제품의 실행 관리 개념입니다. 이 글의 recvWindow 최대값과 연결해 “알고 주문은 60초만 실행된다”고 해석해서는 안 됩니다. 어떤 시간 설정이 요청 단계인지 주문 단계인지 먼저 분류하세요.

9. 배포와 재시작 때 점검할 부분

새 서버를 배포할 때는 시간 동기화 설정이 기존 서버와 같은지 확인합니다. 애플리케이션의 시간 보정값을 영구 저장했다면 오래된 값이 재사용되는지도 점검해야 합니다. 서버 위치나 네트워크 경로가 바뀌었는데 과거 관측을 그대로 믿으면 오차가 생길 수 있습니다.

큐에 저장된 작업을 재시작 후 일괄 전송하는 기능도 주의가 필요합니다. 과거에 서명한 요청을 그대로 보내는지, 현재 거래 의사를 재평가하는지 구분하세요. 복구 과정이 단순히 실패했던 모든 주문을 새 timestamp로 다시 보내는 방식이면 중복 주문 문제와 연결될 수 있습니다.

여러 서버가 하나의 전략을 나눠 실행한다면 각각의 시계와 작업 식별자를 확인해야 합니다. 서버 A의 보정값이 서버 B에도 적합하다고 가정하지 않습니다. 시간 문제를 중앙에서 관리하더라도 실제 요청을 만드는 위치에서 올바른 단위와 값을 사용하는지 검증합니다.

10. 오류별 해결 방향 표

이 표는 진단 출발점입니다. 오류 메시지가 같아도 실제 원인은 다를 수 있으므로 관측값을 모아 판단해야 합니다. 특히 인증 비밀값을 외부에 공유하지 않고도 상당수 시간 문제를 분석할 수 있다는 점을 기억하세요.

시간 문제를 재현할 때의 점검 설계

실제 주문 없이 먼저 검증할 부분

시간값 생성과 단위 변환, 요청 큐 대기, 서명 대상 문자열의 일관성은 실제 매수·매도 없이도 점검할 수 있는 부분입니다. 원인을 찾기 위해 운영 계정에 반복 주문을 보내기보다, 시간 관련 로그와 테스트 환경의 지원 범위를 먼저 확인하는 편이 낫습니다. 테스트 환경과 운영 환경의 지원 기능이 같다고 보장하는 것은 아닙니다.

정상 시계, 의도적으로 오래된 작업, 긴 내부 대기, 잘못된 단위 같은 입력 조건을 분리해 코드가 어떻게 분류하는지 검토할 수 있습니다. 이런 점검은 서버의 보안 검사를 우회하려는 목적이 아니라 프로그램이 잘못된 요청을 스스로 알아차리는지 확인하는 과정입니다. 각 조건에 예상한 오류 분류가 있는지 보는 것이 중요합니다.

왕복 시간과 시계 보정 기록을 함께 보기

서버 시간 조회를 보낸 시각과 응답을 받은 시각을 기록하면 관측 구간을 알 수 있습니다. 응답이 유난히 늦은 표본은 시계 차이 추정에 불확실성이 크다는 점을 표시할 수 있습니다. 하나의 값만 저장하는 대신 관측 시각과 지연 정보를 함께 남기면 나중에 왜 보정값이 달라졌는지 설명하기 쉽습니다.

보정값을 적용하는 위치가 여러 곳인지도 확인하세요. 운영체제가 이미 동기화된 상태에서 라이브러리와 애플리케이션이 각각 별도 보정을 더하면 의도치 않은 오차가 생길 수 있습니다. 어느 계층이 절대 시각을 제공하고 어느 계층이 서버 차이를 보정하는지 역할을 정하는 것이 좋습니다.

경과 시간 측정과 현재 시각 생성 구분

현재 시각을 만드는 기능과 작업에 걸린 시간을 재는 기능은 목적이 다릅니다. 시스템 시각이 동기화 과정에서 조정되면 단순한 시각 차이만으로 측정한 경과 시간에 이상이 생길 수 있습니다. 사용하는 언어가 제공하는 시간 측정 도구의 성격을 확인해 지연 진단과 API timestamp 생성에 적합한 방식을 선택합니다.

이 구분은 특정 언어의 구현을 강제하는 규칙이 아닙니다. 로그에서 대기 시간이 음수로 나오거나 갑자기 큰 값으로 뛰는 상황을 해석하기 위한 점검 항목입니다. 그런 수치가 보였을 때 곧바로 네트워크가 비정상이라고 결론 내리기보다 측정 방식과 시계 변경 이력을 함께 확인하세요.

수정 후 확인할 완료 기준

시간 오류가 한 번 사라진 것만으로 문제 해결을 확정하지 않습니다. 정상 부하와 재시작, 큐가 밀리는 상황에서 timestamp가 적절한 시점에 생성되는지 확인해야 합니다. 서명 오류가 새로 늘지 않았는지, 결과 불명확 주문을 중복 전송하지 않는지도 함께 점검합니다.

변경 기록에는 recvWindow 값만 적지 말고 무엇을 수정했는지 남깁니다. 예를 들어 시간 단위 변환 위치를 하나로 정리했는지, 오래된 서명 요청 재사용을 없앴는지, 보정값 중복 적용을 수정했는지 구체적으로 기록하면 이후 같은 오류가 재발했을 때 비교하기 쉽습니다.

대기 큐를 줄이는 것과 재서명을 구분

큐가 길어지는 원인을 해결하는 작업과 요청을 다시 서명하는 작업은 다른 개선입니다. 재서명만 추가하면 오래된 거래 의사가 최신 요청처럼 전달될 수 있습니다. 반대로 큐를 줄였어도 시스템 시계가 틀렸다면 시간 오류가 남습니다. 어느 변경이 어떤 문제를 해결하는지 나누어 검증해야 합니다.

작업에는 생성 시각과 실행 판단 시각을 따로 남길 수 있습니다. 생성 시각은 전략이 처음 의사를 만든 때이고, 실행 판단 시각은 현재 조건에서도 유효하다고 확인한 때입니다. 이 내부 시각들은 API timestamp를 대신하는 필드가 아니라 오래된 작업을 구분하는 진단 정보입니다.

재시도 간격을 늘렸을 때 생기는 역설

통신 부하를 줄이려고 재시도 간격을 늘렸는데 이미 서명된 요청을 그대로 재사용하면 timestamp는 더 오래될 수 있습니다. 호출량 문제를 해결하면서 시간 유효성 문제를 새로 만드는 셈입니다. 재시도 전에 원래 주문 결과를 확인하고, 필요하다면 현재 조건으로 요청을 다시 구성하는 전체 절차를 검토해야 합니다.

반대로 timestamp를 자동 갱신하는 라이브러리를 사용한다고 모든 문제가 사라지는 것도 아닙니다. 서명 갱신 여부, 원래 작업 식별자 보존, 결과 불명확 주문 처리까지 확인해야 합니다. 라이브러리 이름보다 실제 전송·기록 동작이 판단 기준입니다.

11. FAQ

Q1. 바이낸스 recvWindow는 주문 취소 시간인가요?

아닙니다. 서명된 API 요청의 시간 유효성 범위입니다. 정상 접수된 주문이 얼마나 유지되는지는 주문 종류와 timeInForce 또는 해당 제품의 실행 규칙을 봐야 합니다.

Q2. 기본값과 최대값은 얼마인가요?

현재 확인한 Spot REST 문서는 기본 5,000밀리초, 최대 60,000밀리초를 안내합니다. 이는 이 제품의 설명이며 다른 API에 자동으로 적용하지 않습니다. 최대값이 권장값이라는 의미도 아닙니다.

Q3. 5000은 5초인가요?

recvWindow는 밀리초 단위이므로 5,000밀리초는 5초입니다. timestamp와 소수 정밀도 설명을 섞어 해석하지 마세요. 코드에서 초 단위 값을 반환하는 함수를 사용하는지 확인하는 것이 중요합니다.

Q4. recvWindow를 생략해도 되나요?

해당 요청에서 선택 파라미터로 안내되며 생략 시 기본값이 적용됩니다. 다만 명시 여부와 관계없이 timestamp와 서명 등 필요한 조건을 충족해야 합니다. 생략이 시간 검증 자체를 끄는 것은 아닙니다.

Q5. PC 시간대가 한국이면 9시간을 더해야 하나요?

시간대 표시와 절대 타임스탬프를 구분해야 합니다. 올바른 Unix 시각을 만드는 함수라면 화면 시간대 차이를 이유로 임의 보정하지 않습니다. 9시간을 더하는 조치는 오히려 잘못된 요청을 만들 수 있습니다.

Q6. 서버보다 시간이 앞서면 큰 recvWindow로 해결되나요?

미래 쪽 timestamp 검사는 오래된 요청의 허용 범위와 구분됩니다. 앞선 시각 오류가 확인되면 시스템 동기화와 보정값을 점검해야 합니다. 값을 크게 하는 것만으로 정상 시계가 되는 것은 아닙니다.

Q7. 요청 전 서버 시간을 매번 조회해야 하나요?

공식 서버 시간 경로는 유용하지만 모든 요청 앞에 무조건 추가 조회해야 한다는 뜻은 아닙니다. 동기화 품질과 호출 예산을 고려한 정책을 마련하세요. 잦은 조회 자체도 요청량을 늘립니다.

Q8. timestamp만 수정하고 서명은 그대로 써도 되나요?

서명 대상 파라미터가 바뀌면 그 내용에 맞는 서명이 필요합니다. 이미 서명한 요청의 시간값만 수정하는 구조는 서명 오류를 만들 수 있습니다. 최종 파라미터 확정과 서명 순서를 확인하세요.

Q9. 인터넷이 빠른데 왜 시간 오류가 나나요?

시계 오차, 단위 혼동, 내부 작업 큐, 오래된 서명 요청 재사용 등 네트워크 외 원인도 있습니다. 요청 생성과 전송 시각을 나눠 관찰하면 어느 구간에서 시간이 소모됐는지 파악하는 데 도움이 됩니다.

Q10. timeout이면 주문이 실패한 것인가요?

응답을 받지 못했다는 사실만으로 서버의 미접수를 확정할 수 없는 경우가 있습니다. 원래 주문 식별자로 상태를 확인하는 절차가 필요합니다. 새 timestamp를 만든다고 원래 주문의 결과가 밝혀지는 것은 아닙니다.

Q11. -1021과 -1022는 같은 오류인가요?

아닙니다. 전자는 timestamp 관련 오류이고 후자는 서명 관련 오류입니다. 재시도 과정에서 시간값만 바꾸고 서명을 갱신하지 않았다면 오류 종류가 바뀔 수도 있으므로 실제 응답을 읽어야 합니다.

Q12. 소수점 recvWindow는 필수인가요?

지원되는 정밀도와 반드시 사용해야 하는 형식은 다릅니다. 필요한 경우에만 라이브러리의 직렬화와 서명 처리를 확인해 사용합니다. 복잡한 표현을 도입하는 것이 자동으로 지연이나 체결 품질을 개선하지 않습니다.

Q13. 선물 API에도 이 값을 그대로 적용하나요?

제품별 공식 규격을 확인해야 합니다. 같은 이름의 필드가 있어도 지원 단위나 제약을 이 글만으로 일반화하지 않습니다. 사용하는 서비스·메서드·경로를 정확히 구분한 뒤 해당 문서를 보세요.

Q14. 작은 값일수록 무조건 좋은가요?

공식 문서는 작은 값을 권장하지만, 근거 없이 지나치게 좁히면 정상 지연에도 거절이 늘 수 있습니다. 실제 시계 동기화와 지연 관측을 바탕으로 검토해야 합니다. 이 설정은 수익이나 체결을 보장하지 않습니다.

Q15. 다음으로 공부할 개념은 무엇인가요?

결과가 불명확한 요청을 추적하는 clientOrderId가 자연스럽게 이어집니다. 요청을 시간상 유효하게 만드는 것과 어떤 주문이 실제 접수됐는지 확인하는 것은 별도 문제이므로, 식별자와 상태 관리까지 함께 이해하는 편이 좋습니다.

12. 운영 체크리스트

• API 제품과 환경을 정확히 구분했다.
• timestamp를 만드는 함수의 단위를 확인했다.
• recvWindow의 밀리초 단위를 확인했다.
• 시스템 시간 동기화 상태를 점검했다.
• 시간대 표시를 절대 시각 보정과 혼동하지 않는다.
• 요청 생성·전송·응답 시각을 구분해 기록한다.
• 긴 큐에서 오래된 서명 요청을 재사용하지 않는다.
• 최종 파라미터와 서명 대상 내용이 일치한다.
• -1021과 -1022를 따로 분류한다.
• 클라이언트 timeout을 미접수로 단정하지 않는다.
• 재시작 후 저장된 작업을 재평가한다.
• 서버별 보정값과 동기화 상태를 확인한다.
• Secret과 인증 헤더를 일반 로그에 남기지 않는다.
• 설정 변경 후 오류와 지연을 함께 관찰한다.

핵심 정리와 다음 단계

바이낸스 recvWindow는 큰 숫자를 넣어 오류를 숨기는 옵션이 아니라, 요청 시각과 전송 과정을 이해하면서 사용하는 시간 검증 요소입니다. 시계 동기화, 단위 일관성, 서명 순서, 중복 없는 복구 절차를 함께 점검해야 의미가 있습니다.

이 글은 API 동작을 설명하는 정보성 자료입니다. 주문 실행이나 수익을 보장하지 않으며, 실제 운영 전 최신 Binance 공식 문서와 사용하는 도구의 규격을 확인하세요.