제휴 안내: 이 글에는 OKX 파트너 링크가 포함되어 있습니다. 해당 링크를 통해 가입·거래하면 운영자에게 수익이 발생할 수 있습니다. 이용자 혜택은 계정·지역·VIP 등급·캠페인에 따라 달라질 수 있으므로 가입 화면과 My Rewards에서 실제 적용 조건을 확인하세요.
결론부터 말하면, OKX API 오류 50113 Invalid signature는 서버가 다시 계산한 서명과 요청의 OK-ACCESS-SIGN 값이 다를 때 발생합니다. 먼저 timestamp + method + requestPath + body를 실제 전송값과 한 글자까지 같게 만들고 HMAC SHA256 후 Base64로 인코딩하세요. 함께 나타나는 50102·50101은 각각 UTC 시간과 실거래·Demo 환경부터 분리해 점검해야 합니다.
보안·거래 위험: 오류를 고치기 위해 Secret Key·Passphrase를 로그, 화면 캡처, Git 저장소 또는 공개 질문 글에 붙여 넣지 마세요. Trade 권한이 있는 키가 노출되면 출금 권한이 없어도 무단 주문·레버리지 확대·수수료 누적·청산이 발생할 수 있습니다. 실거래 재시도 전에는 열린 주문과 포지션, 주문 수량, 계정 모드와 환경을 확인하세요.
OKX API 오류 코드 빠른 진단표
| 오류 코드 | 조건·확인 사항 |
|---|---|
| 50113 | 공식 메시지: Invalid signature 가장 먼저 볼 항목: 서명 전 문자열과 실제 요청의 일치 안전한 첫 조치: 키를 바꾸기 전에 timestamp·method·path·body를 각각 비교 |
| 50102 | 공식 메시지: Timestamp request expired 가장 먼저 볼 항목: UTC 시간과 서버 시간 차이 안전한 첫 조치: GET /api/v5/public/time으로 동기화 확인 |
| 50101 | 공식 메시지: APIKey does not match current environment 가장 먼저 볼 항목: 실거래 키·Demo 키와 요청 환경 안전한 첫 조치: Demo 전용 키와 x-simulated-trading: 1 확인 |
| 50105 | 공식 메시지: OK-ACCESS-PASSPHRASE incorrect 가장 먼저 볼 항목: 키 생성 시 정한 Passphrase 안전한 첫 조치: 추측 반복 대신 분실 시 새 키 생성 |
| 50110 | 공식 메시지: IP not in API key whitelist 가장 먼저 볼 항목: 서버의 실제 공인 IP 안전한 첫 조치: IP 제한을 해제하지 말고 허용목록과 송신 IP 대조 |
| 50120 | 공식 메시지: API key has no permission 가장 먼저 볼 항목: 요청 기능과 Read·Trade 등 권한 안전한 첫 조치: 필요한 최소 권한만 추가 |
| 50011 | 공식 메시지: Rate limit reached 가장 먼저 볼 항목: 엔드포인트별 호출 한도 안전한 첫 조치: 백오프·큐·재시도 상한 적용 |
OKX 공식 오류표에는 일부 애플리케이션 오류가 HTTP 200과 함께 반환되는 항목도 있습니다. 따라서 HTTP 상태만 보고 성공으로 처리하지 말고 응답의 code와 msg를 함께 검사해야 합니다. 표의 해결 순서는 AKEYX가 공식 메시지와 인증 규칙을 바탕으로 정리한 진단 순서이며, 비밀값을 노출하라는 의미가 아닙니다.
함께 구분할 오류: 50119 API key doesn’t exist 오류만으로 키가 폐기·삭제됐다고 단정하지 말고 계정 등록 지역과 요청 도메인·서브계정의 키 연결을 확인합니다. 50004 API endpoint request timeout은 성공·실패 어느 쪽도 확정하지 않으므로, 주문 결과를 조회하기 전에 같은 주문을 다시 보내지 마세요. 공식 오류표와 API FAQ의 적용 조건을 기준으로 분리합니다.
지원되는 오류 코드와 연결 방식·실거래/Demo 환경에 따른 확인 순서는 API 오류 코드 찾기에서 살펴볼 수 있습니다. API 키·Secret·Passphrase·로그 원문을 입력하지 않는 선택형 안내이며, 실제 API 요청을 실행하거나 계정 상태·원인을 확정하지 않습니다.
50113 Invalid signature는 무엇을 뜻하나?
50113은 “API 키가 무조건 틀렸다”는 뜻이 아니라, OKX가 같은 요청 정보로 계산한 서명과 클라이언트가 보낸 서명이 일치하지 않는다는 뜻입니다. 같은 Secret Key를 사용해도 타임스탬프, HTTP 메서드, 쿼리 문자열, 요청 경로 또는 JSON 본문 중 하나가 달라지면 서명은 완전히 달라집니다.
키 생성·권한·IP 제한의 기본 개념을 먼저 확인해야 한다면 OKX API 키 생성·보안 가이드를 참고하세요. 이 글은 키를 이미 만들었지만 인증 요청이 실패하는 상황만 별도 검색 의도로 다룹니다.
공식 서명 공식과 네 가지 입력값
OKX REST 인증 문서의 서명 순서는 다음과 같습니다.
preHash = timestamp + method + requestPath + body
signature = Base64(HMAC_SHA256(preHash, SecretKey))| 입력값 | 조건·확인 사항 |
|---|---|
| timestamp | 공식 조건: OK-ACCESS-TIMESTAMP와 같은 ISO 8601 UTC 값자주 생기는 차이: 로컬 시간대, 밀리초 누락, 서명 후 시간 재생성 검증 방법: 헤더와 preHash에 들어간 문자열을 비밀값 없이 길이·해시로 비교 |
| method | 공식 조건: GET·POST처럼 대문자 자주 생기는 차이: get, 앞뒤 공백검증 방법: 전송 직전 대문자 고정 |
| requestPath | 공식 조건: 도메인을 제외한 경로, GET 쿼리 포함 자주 생기는 차이: 호스트 포함, 쿼리 순서·인코딩 차이, 끝 슬래시 검증 방법: HTTP 클라이언트가 실제 전송한 path와 비교 |
| body | 공식 조건: GET은 보통 빈 문자열, POST는 실제 전송 JSON 문자열 자주 생기는 차이: 서명 후 JSON 재직렬화, 공백·키 순서·숫자 형식 변화 검증 방법: 서명한 본문과 전송 바이트가 같은지 확인 |
GET 요청 예시
timestamp = "2026-08-25T00:00:00.000Z"
method = "GET"
requestPath = "/api/v5/account/balance?ccy=BTC"
body = ""
preHash = timestamp + method + requestPath + body쿼리 문자열 ?ccy=BTC를 실제 요청에는 붙였지만 서명에서는 뺀 경우, 또는 서명 후 HTTP 라이브러리가 쿼리 순서를 바꾼 경우 50113이 발생할 수 있습니다. 반대로 https://www.okx.com 같은 호스트 전체를 requestPath에 포함하지 않습니다.
POST 요청 예시
body = '{"instId":"BTC-USDT","tdMode":"cash","side":"buy","ordType":"limit","px":"10000","sz":"0.001"}'
preHash = timestamp + "POST" + "/api/v5/trade/order" + bodyAKEYX 진단 원칙: 서명할 때 사용한 JSON 문자열을 그대로 전송하세요. 객체를 다시 직렬화하면서 공백, 키 순서 또는 숫자 표현이 달라지면 서버가 보는 본문과 서명 입력이 달라질 수 있습니다. 예시는 형식 설명용이며 실제 주문 가격·수량 추천이 아닙니다.
50113 해결 순서: 키를 재발급하기 전에 확인할 8단계
- 실거래 전송을 멈춥니다. 자동 재시도가 주문 중복이나 속도 제한으로 이어지지 않도록 큐를 중지합니다.
- 오류 응답을 분리합니다. HTTP 상태와 함께
code,msg, 엔드포인트, 발생 시각만 기록합니다. - 타임스탬프를 한 번만 생성합니다. 같은 값을 헤더와 preHash에 사용합니다.
- 메서드를 대문자로 고정합니다. GET·POST와 실제 전송 메서드가 같은지 확인합니다.
- 최종 requestPath를 비교합니다. GET 쿼리 문자열과 인코딩·순서를 포함하되 호스트는 제외합니다.
- POST 본문을 고정합니다. 서명한 JSON 문자열을 수정 없이 전송합니다.
- HMAC SHA256과 Base64 순서를 확인합니다. 16진수 문자열을 다시 Base64 처리하는 등 라이브러리 출력 형식을 혼동하지 않습니다.
- 그래도 실패하면 환경과 자격 증명을 분리합니다. Demo·실거래 키, 지역 도메인, Passphrase, IP와 권한을 다음 절차로 점검합니다.
디버깅 로그에는 Secret Key와 Passphrase를 절대 넣지 마세요. 필요한 경우 preHash 자체 대신 길이, 요청 구성요소별 길이, 비밀값을 제외한 requestPath와 body의 단방향 해시만 제한된 보안 로그에 기록합니다.
50102 Timestamp request expired 해결
OKX 공식 문서는 OK-ACCESS-TIMESTAMP를 밀리초 정밀도의 ISO 8601 UTC 형식으로 보내고, 서버 시간과 30초를 초과해 차이 나는 요청을 거부한다고 설명합니다. 로컬 시간대 오프셋을 UTC로 착각하는 것이 대표 원인이며, 주문 전에 GET /api/v5/public/time을 사용해 서버 시간과 동기화를 확인하도록 안내합니다.
- 운영체제와 컨테이너의 시간 동기화 상태를 확인합니다.
Z가 붙은 UTC 문자열인지 확인합니다.- 요청 큐에서 오래 대기한 뒤 과거 타임스탬프로 전송되지 않는지 확인합니다.
- 서명한 뒤 재시도 모듈이 timestamp 헤더만 바꾸지 않는지 확인합니다.
- 서버 시간 보정값을 적용하더라도 매 요청마다 누적하지 않습니다.
시간 필드는 서로 바꿔 쓰지 않습니다. REST의 OK-ACCESS-TIMESTAMP는 밀리초 정밀도 ISO 8601 UTC 문자열, WebSocket login의 timestamp는 Unix 초입니다. 지원되는 주문·정정 요청의 선택 헤더 expTime은 Unix 밀리초의 유효 기한이며 인증 timestamp나 서버 시간 동기화를 대신하지 않습니다. 위 고정 날짜 코드는 형식 설명용이므로 실제 요청에 재사용하지 마세요. REST 인증과 expTime 지원 범위를 각각 확인합니다.
50101: 실거래·Demo 환경과 지역 API 도메인
50101은 API 키와 현재 요청 환경이 맞지 않을 때 반환됩니다. OKX 공식 문서는 Demo Trading에서 별도의 Demo API 키를 만들고 Demo 요청 헤더에 x-simulated-trading: 1을 추가하도록 안내합니다. 실거래 키를 Demo 요청에 섞거나 그 반대로 사용하지 마세요.
| 점검 대상 | 조건·확인 사항 |
|---|---|
| API 키 | 실거래: 실거래 API 메뉴에서 생성한 키 Demo Trading: Demo Trading 전용 경로에서 생성한 키 실패 예방: 키 이름과 환경 변수 접두사를 분리 |
| 추가 헤더 | 실거래: Demo 헤더를 임의로 붙이지 않음 Demo Trading: x-simulated-trading: 1실패 예방: 환경별 공통 HTTP 클라이언트를 분리 |
| 주문 검증 | 실거래: 소액·최소 권한·손실 상한 Demo Trading: 주문 흐름과 파라미터 시험 실패 예방: Demo 성과를 실거래 수익으로 가정하지 않음 |
| 지역 도메인 | 실거래·Demo Trading: 계정 등록 지역의 공식 API 도메인 사용 실패 예방: US·AU와 EU 등록 계정은 공식 지역별 도메인 안내 확인 |
2026년 10월 25일 확인한 OKX API 문서의 지역 안내는 app.okx.com에 등록된 US·AU 계정은 us.okx.com, my.okx.com에 등록된 EU 계정은 eea.okx.com API 도메인과 해당 문서를 사용하도록 명시합니다. 지역을 우회하지 말고 내 계정 등록 위치에 표시된 공식 도메인을 사용하세요.
50119와 SDK도 함께 점검: 키가 존재하더라도 계정 등록 지역과 API 호스트가 맞지 않거나 타사 도구가 지역 도메인을 지원하지 않으면 연결이 실패할 수 있습니다. 50119 하나만 보고 키가 삭제됐다고 단정하거나 다른 지역 호스트를 무작위로 시도하지 마세요. 키를 발급한 본·서브계정, 지역용 공식 문서, SDK의 실거래·Demo 설정과 실제 요청 헤더를 함께 확인합니다. 글로벌 문서에서는 실거래와 Demo의 REST 호스트가 같을 수 있으므로 호스트 이름만으로 환경을 판정하지 않습니다.
50105·50110·50120: Passphrase·IP·권한 문제
50105 Passphrase incorrect
OK-ACCESS-PASSPHRASE는 OKX 로그인 비밀번호가 아니라 API 키를 만들 때 사용자가 정한 별도 문자열입니다. 공식 FAQ는 분실한 Passphrase를 복구할 수 없다고 안내합니다. 대소문자·공백·환경 변수 매핑을 확인하되, 기억나지 않는 값을 반복 추측하지 말고 기존 키를 폐기한 뒤 새 키를 만드세요.
50110 IP whitelist
오류 메시지에 표시된 송신 IP가 API 키의 허용목록에 없다는 뜻입니다. 서버가 NAT, 프록시 또는 클라우드 게이트웨이를 거친다면 애플리케이션 내부 IP가 아니라 OKX에 보이는 실제 공인 송신 IP를 확인해야 합니다. 오류를 없애려고 IP 제한 전체를 해제하거나 임의의 넓은 네트워크 범위를 허용하지 마세요.
50120 permission
요청 기능을 사용할 권한이 API 키에 없다는 뜻입니다. 잔액 조회만 필요하면 Read, 주문 제출·취소가 필요하면 Trade처럼 목적과 권한을 대조하세요. 하나의 오류를 이유로 Withdraw까지 모두 켜는 것은 해결책이 아닙니다. 계정 전반의 방어 설정은 OKX 안전성·계정 보안 가이드에서 확인할 수 있습니다.
50011 Rate limit reached 해결
OKX는 엔드포인트별로 다른 호출 한도를 적용하며, 한도 초과 시 50011을 반환한다고 설명합니다. 공개 REST는 IP 기준, 비공개 REST는 사용자 ID 기준 등 한도 기준도 요청 종류에 따라 달라질 수 있습니다. 고정 지연으로 무한 재시도하지 말고 엔드포인트 문서의 한도에 맞춰 요청을 설계하세요.
- 429 또는 50011을 성공 응답으로 오인하지 않습니다.
- 지수 백오프와 무작위 지연을 적용합니다.
- 재시도 횟수와 총 대기 시간에 상한을 둡니다.
- 동일 데이터 조회를 캐시하고 중복 폴링을 합칩니다.
- 주문 생성 재시도에는 고유한 client order ID와 상태 조회 절차를 둡니다.
- WebSocket 구독과 REST 폴링의 역할을 분리합니다.
REST와 WebSocket을 분리해 한도를 늘렸다고 가정하지 않습니다. 공식 문서는 주문 생성·정정·취소의 해당 한도가 REST와 WebSocket 사이에 공유되고, 생성·정정·취소는 서로 독립적인 한도를 가질 수 있다고 안내합니다. 상품·사용자·엔드포인트별 조건을 한 곳에서 계산하고, 50011은 HTTP 200이나 429 등 공식 표에 제시된 응답 형태를 함께 처리하세요. 재시도 간격·횟수 상한은 AKEYX의 운영상 권고이지 공식 한도를 늘리는 방법이 아닙니다.
50004 시간초과: 재전송보다 주문 결과 확인이 먼저
50004 또는 통신 단절은 요청이 처리되지 않았다는 증거가 아닙니다. 자동 주문 큐를 멈추고, 전송 당시의 요청 ID·clOrdId·ordId·발생 시각을 비밀값 없이 보존한 뒤 공식 주문 조회와 주문·체결 이력, 필요하면 포지션·잔액을 대조하세요. 결과가 불명확한 동안에는 새 ID로 같은 주문을 보내거나 동일 요청을 무한 반복하지 않습니다. 50004 공식 오류 정의는 실제 요청 결과를 확인하도록 명시합니다.
응답을 세 단계로 구분: HTTP 상태 → 최상위 code·msg → 주문별 data[].sCode·sMsg를 확인하고 해당 엔드포인트의 결과 필드를 해석합니다. 주문 요청 접수·처리 성공과 체결 완료는 다른 상태이므로, code: "0"이나 주문 ID가 있다는 이유만으로 체결됐다고 기록하지 마세요. 복수 주문은 각 항목의 결과를 따로 확인합니다.
clOrdId는 무제한 중복 방지 보증이 아닙니다. 공식 일반 주문 명세는 계정의 현재 미체결·부분체결 주문 사이에서 고유해야 하며, 종료된 주문 뒤에는 같은 값을 재사용할 수 있고 과거 전체의 고유성은 강제되지 않는다고 설명합니다. 같은 값이 여러 주문에 사용됐다면 주문 상세 조회는 최신 일치 항목만 반환할 수 있습니다. 가능하면 반환된 ordId와 시각·이력을 함께 대조하고, 중복 방지 키 하나만으로 재시도가 안전하다고 가정하지 마세요. 일반 주문 응답·clOrdId 조건을 확인하세요.
실패 사례별 원인 분리
| 증상 | 조건·확인 사항 |
|---|---|
| GET만 50113 | 가능성이 높은 원인: 쿼리 문자열 누락·순서·인코딩 확인 증거: 최종 전송 URL과 서명 path 비교 피해야 할 대응: 키를 무작정 재발급 |
| POST만 50113 | 가능성이 높은 원인: 서명 후 JSON 본문 변경 확인 증거: 전송 본문 해시와 서명 본문 해시 비교 피해야 할 대응: Secret을 로그에 출력 |
| 간헐적 50102 | 가능성이 높은 원인: 큐 지연·재시도 시 과거 시간 사용 확인 증거: 생성 시각과 실제 전송 시각 차이 피해야 할 대응: 허용 오차를 임의로 늘렸다고 가정 |
| Demo에서만 50101 | 가능성이 높은 원인: 키·헤더·환경 혼합 확인 증거: 키 생성 위치와 x-simulated-trading피해야 할 대응: 실거래 키로 반복 요청 |
| 배포 후 50110 | 가능성이 높은 원인: 송신 공인 IP 변경 확인 증거: 배포 인프라의 egress IP 피해야 할 대응: IP 제한 전체 해제 |
| HTTP 200인데 실패 | 가능성이 높은 원인: 응답 code가 0이 아님 확인 증거: code·msg 파싱피해야 할 대응: HTTP 상태만 성공 판정 |
안전한 디버깅 로그 체크리스트
- □ 오류 코드, HTTP 상태, 엔드포인트, UTC 발생 시각만 기록했는가?
- □ API Key 전체 대신 마지막 몇 글자 또는 내부 키 이름만 기록했는가?
- □ Secret Key와 Passphrase를 완전히 제외했는가?
- □ requestPath와 body에 개인정보·잔액·주문 정보가 있는지 확인했는가?
- □ preHash 전체 대신 구성요소 길이와 단방향 해시로 비교했는가?
- □ 로그 접근 권한과 보관 기간을 제한했는가?
- □ 실거래 재시도 전에 열린 주문·포지션을 조회했는가?
자동 주문 자체의 레버리지·마진·청산 위험을 아직 이해하지 못했다면 OKX 선물거래 초보자 가이드를 먼저 읽고 Demo 환경에서 주문 흐름을 확인하세요. API 인증 성공은 전략의 수익성이나 주문의 안전성을 보장하지 않습니다.
키 유출이나 예상 밖 주문이 의심될 때
- 해당 API 키를 즉시 폐기합니다.
- 봇과 재시도 큐를 중지합니다.
- 열린 주문·포지션·내부 이체·출금 기록을 확인합니다.
- 다른 API 키와 로그인 세션, 2FA·Passkey 상태를 점검합니다.
- 공개 저장소와 로그에서 비밀값을 제거하되 노출된 키는 재사용하지 않습니다.
- 새 키가 필요하다면 새 Passphrase, 최소 권한과 신뢰 IP로 다시 생성합니다.
API 키 폐기와 열린 주문 취소·포지션 정리는 서로 다른 작업입니다. 키를 폐기했다고 주문·포지션이 모두 종료됐다고 가정하지 말고, 공식 계정 화면과 고객지원에서 실제 상태를 확인하세요. 로그에 남긴 본문 해시나 키의 일부 문자열도 완전한 익명화를 보장하지 않으므로 접근 권한·보관 기간을 제한합니다. WebSocket 인증의 별도 서명 경로와 복구 절차는 OKX WebSocket 연결·재연결 안내에서 구분해 확인할 수 있습니다.
자주 묻는 질문
50113이 나오면 API 키부터 다시 만들어야 하나요?
아닙니다. 먼저 timestamp·method·requestPath·body와 HMAC SHA256·Base64 순서를 비교하세요. 자격 증명 노출, Passphrase 분실 또는 키 상태 이상이 확인될 때 새 키를 만드는 것이 안전합니다.
GET 요청도 body를 서명해야 하나요?
OKX 문서 예시처럼 GET은 보통 body를 빈 문자열로 두며, 쿼리 문자열은 requestPath에 포함합니다. 사용하는 엔드포인트의 최신 공식 예시와 실제 전송값을 우선하세요.
50102를 피하려면 컴퓨터 시간을 한국 시간으로 맞춰야 하나요?
요청 헤더는 로컬 표시 시간이 아니라 ISO 8601 UTC를 사용합니다. OKX 서버 시간 엔드포인트와 시스템 시간 동기화를 확인하고 같은 timestamp를 헤더와 서명에 사용하세요.
Demo API 키로 실거래 주문을 보낼 수 있나요?
Demo와 실거래 키는 분리해야 합니다. Demo 요청은 Demo 전용 키와 x-simulated-trading: 1 헤더를 사용하며, 환경을 섞으면 50101 같은 인증 실패가 발생할 수 있습니다.
50110을 없애려고 IP 허용목록을 비워도 되나요?
권장하지 않습니다. 실제 공인 송신 IP와 허용목록을 정확히 대조하고, NAT·프록시·클라우드 egress 변경을 확인하세요. 제한 해제는 키 유출 시 공격 범위를 넓힐 수 있습니다.
OKDCC를 쓰면 API 오류나 거래 손실이 줄어드나요?
아닙니다. 추천코드는 API 인증·전략 성능·시장 위험과 별개입니다. 표시 가능한 최대 수수료 혜택도 자동·무조건 적용이 아니며 계정·지역·VIP·캠페인에 따라 달라질 수 있으므로 가입 전 화면과 가입 후 My Rewards에서 실제 적용률을 확인해야 합니다.
공식 자료와 검토일
- OKX API V5: REST Authentication — 헤더·서명 공식·30초 시간 조건
- OKX API V5: REST API Error Codes — 50011·50101·50102·50105·50110·50113·50120
- OKX API FAQ — 공식 FAQ 수정일 2026년 9월 28일; 키·Passphrase·Demo·만료 안내. AKEYX 검토일 2026년 10월 25일
- OKX: Subaccounts, Account Mode, and API Connections FAQ — 계정·권한·연결 조건
최종 검토일: 2026년 10월 25일. 오류 코드, 지역 도메인, 인증 형식, 엔드포인트와 호출 한도는 변경될 수 있습니다. 공식 사실과 AKEYX의 진단 순서를 구분해 읽고, 실제 요청 전에는 내 계정에 맞는 최신 OKX API 문서와 로그인 화면을 다시 확인하세요.