API 공통 문의

REST API 요청 시 오류가 발생합니다.

API 요청 처리 중 오류가 발생한 경우 HTTP 응답 본문(Body)에 에러 코드가 함께 반환됩니다. 주요 에러 코드는 REST API 사용 안내 페이지 및 각 API Reference 문서 우측 하단 응답 예시에서 확인하실 수 있습니다.

만약 위 문서에서 확인되지 않는 오류에 대해 발생 원인을 확인할 수 없는 경우 해당 에러 코드를 포함하여 문의([email protected])주시기 바랍니다.

---

파라미터를 정확하게 입력했음에도 Invalid parameter. Check the given value! 에러가 발생합니다.

파라미터에 : 또는 +와 같은 특수 문자가 포함되었을 때(주로 날짜 형식), 쿼리 문자열을 URL 인코딩 없이 요청하는 경우 위와 같은 에러가 발생할 수 있습니다.

REST API 사용 및 에러 안내 페이지 또는 첫 업비트 API 호출하기 페이지를 참고하여 URL 인코딩 후 요청해주세요.

URL 인코딩이란?

URL 인코딩은 통신 프로토콜에서 URL 내에 포함할 수 없는 문자를 전송 가능한 문자로 변환하는 인코딩 방식입니다. 특수 문자를 포함한 대상 문자들은 인코딩 시 % 기호와 2자리 16진수로 이루어진 문자열로 변환됩니다.

• : → %3A
• + → %2B

---

API Key 허용 IP 주소 목록에 현재 사용 중인 IP를 추가해도 오류가 발생합니다.

로컬 네트워크에서 확인되는 IP 주소와 실제 통신에 사용하는 IP 주소가 다른 경우 문제가 발생할 수 있습니다.

• 로컬 PC를 이용하는 경우: 구글 등의 검색엔진에서 what is my ip 또는 내 IP 주소 등을 검색하여 확인된 공인 IP 주소
• 서버를 이용하는 경우: 서버의 외부망 통신에 사용하는 공인 IP 주소

API Key에 등록한 IP 주소와 실제 API 요청에 사용되는 공인 IP 주소가 동일한지 확인한 후 다시 시도해주세요.

---

유동 IP 환경에서 API를 사용하고 싶습니다.

API Key 기반 인증을 통한 Exchange API 호출은 고정 IP 환경에서 허용 IP 목록을 등록한 후 사용할 수 있습니다.

자산 입출금 및 주문과 관련된 민감한 기능인 만큼, 회원님의 자산을 안전하게 보호하기 위한 조치이므로 클라우드 서버 또는 고정 IP 서비스를 통해 이용해주시기 바랍니다.

---

Public WebSocket과 Private WebSocket은 무엇이 다른가요?

업비트 WebSocket은 API Key 인증 필요 여부에 따라 Public과 Private으로 구분됩니다.

Public WebSocket은 API Key 인증 없이 이용할 수 있으며, 현재가·체결·호가 등 공개된 시세 데이터를 구독할 때 사용합니다.

Private WebSocket은 API Key를 이용한 인증이 필요하며, 인증이 필요한 데이터 타입을 구독할 때 사용합니다.

Private WebSocket이라고 해서 모든 데이터 타입에 별도의 API Key 권한이 필요한 것은 아닙니다. API Key 권한 필요 여부는 구독하는 데이터 타입에 따라 다르게 적용됩니다.

자세한 연결 및 인증 방법은 WebSocket 사용 및 에러 안내를 참고해주세요.

---

기존 API Key로 REST API와 Private WebSocket을 함께 이용해도 되나요?

네, 함께 이용할 수 있습니다.

예를 들어 주문 권한이 설정된 기존 API Key로 REST API를 통해 주문을 요청하면서, 동일한 API Key를 Private WebSocket 인증에도 사용할 수 있습니다.

이때 동일한 API Key를 사용하더라도 REST API와 WebSocket의 요청 수 제한이 하나로 합산되는 것은 아닙니다.

요청 수 제한(Rate Limit)은 각 API에 정의된 Rate Limit 그룹과 측정 단위에 따라 적용됩니다. REST API 요청과 WebSocket 연결 및 데이터 요청은 각각 해당하는 요청 수 제한 정책에 따라 관리됩니다.

따라서 Private WebSocket을 구독하는 것만으로 동일한 API Key를 이용한 주문 API의 요청 가능 횟수가 차감되지는 않습니다.

자세한 내용은 요청 수 제한(Rate Limits)을 참고해주세요.

---

인증서 에러가 발생합니다. (SSL: CERTIFICATE_VERIFY_FAILED)

로컬 환경의 인증서 업데이트를 통한 최신 인증서 반영을 권장합니다.

• Windows → 최신 버전 업데이트
• macOS → 최신 버전 업데이트
• Linux → apt-get install ca-certificates

---

요청이 잘 처리되었었는데, 최근 에러 발생 빈도가 높아졌습니다.

DNS 캐시 문제일 가능성이 높습니다. 로컬 환경의 DNS 캐시 초기화를 통한 조치를 권장합니다.

• Windows → ipconfig /flushdns

---

CORS 에러가 발생합니다.

시세 조회 관련 REST API, WebSocket 요청에 Origin 헤더가 존재하는 경우 요청 수 제한이 10초당 1회로 상향 제한됩니다.

• 관련 공지 바로가기
• 해당 정책이 적용된 경우 응답의 Remaining-Req 헤더가 group=origin으로 반환됩니다.
• 요청 수 제한을 초과한 요청에 대해 CORS 에러가 발생할 수 있습니다.
• 브라우저에서 요청이 필요한 경우 제한에 맞추어 요청하거나 별도의 프록시 서버를 구성하여 사용하시기 바랍니다.