REST API 사용 및 에러 안내

Endpoint

https://api.upbit.com/v1

Content Type

업비트 REST API는 application/json Content Type을 지원합니다. 특히 POST 요청의 경우, 본문(Body)을 JSON 형식으로 요청해야 하며 아래 헤더를 함께 지정하여 주시기 바랍니다.

Content-Type: application/json; charset=utf-8

POST API에 대한 Form 방식 요청은 2022년 3월 1일부로 지원이 종료되었습니다.

Form 방식 지원 종료에 따라 Urlencoded Form 방식으로 전송하는 POST 요청에 대한 정상적인 동작을 보장하지 않습니다. 반드시 JSON 형식으로 요청 본문(Body)을 전송해주시기 바랍니다.

인증

인증이 필요한 Exchange API 요청 시 인증 가이드를 참고하여 생성한 JWT 토큰을 Authorization 헤더에 반드시 포함하여 요청해야 합니다. 업비트 REST API는 Bearer 인증을 지원하며, 아래와 같은 형식으로 입력합니다.

Authorization: Bearer eyJhb...d8sTw

요청 수 제한

REST API 요청 수 제한 정책은 요청 수 제한(Rate Limits)문서를 참조하시기 바랍니다.

응답 상태 코드 및 에러 안내

업비트 REST API 응답으로 반환되는 HTTP 상태 코드 목록과 각 코드의 의미는 아래와 같습니다.

HTTP Status Code	관련 에러 코드	발생 이유	에러 해결 방법
200 OK	-	정상 응답	-
201 Created	-	요청으로 인한 생성 완료	-
400 Bad Request	`create_ask_error`, `create_bid_error`	주문 요청 정보가 올바르지 않습니다.	시장가 주문임에도 가격을 입력하는 경우 발생할 수 있습니다. 주문 생성 문서를 참고해주세요.
	`insufficient_funds_ask`, `insufficient_funds_bid`	매수/매도 가능 잔고가 부족합니다.	잔고를 확인해주세요.
	`under_min_total_ask`, `under_min_total_bid`	최소 주문 금액에 미달합니다.	페어별 최소 주문 금액 확인 후 재요청해주세요.
	`withdraw_address _not_registered`	허용되지 않은 출금 주소입니다.	등록된 출금 주소 목록에 포함되어 있는지 확인해주세요.
	`validation_error`	잘못된 API 요청입니다.	필수 파라미터 누락 여부를 확인해주세요.
401 Unauthorized	`invalid_query_payload`	JWT 페이로드가 올바르지 않습니다.	인증 가이드 문서를 참고하여 서명이 올바르게 생성 되었는지 확인해주세요.
	`jwt_verification`	JWT 검증에 실패했습니다.	토큰의 생성 및 서명 상태를 점검해주세요.
	`expired_access_key`	API 키가 만료되었습니다.	새로운 키를 발급받아 사용해주세요.
	`nonce_used`	이미 사용된 nonce 값입니다.	JWT에는 매 요청마다 새로운 nonce 값을 사용해야 합니다.
	`no_authorization_ip`	등록되지 않은 IP입니다.	API 키 발급 시 등록한 IP 환경에서 호출 중인지 점검해주세요.
	`no_authorization_token`	인증 토큰이 누락되었습니다.	인증 헤더가 요청에 포함되었는지 확인해주세요.
	`out_of_scope`	지원 범위를 벗어난 기능입니다.	API 키 발급 시 해당 기능을 포함했는지 확인해주세요.
404 Not Found	-	존재하지 않는 데이터에 접근	주문, 출금, 입금, 체결 등 요청 항목이 존재하지 않는 경우
418 I'm a teapot	-	과도한 요청으로 인해 거부되었습니다.	IP 차단 등으로 요청이 제한됩니다.
429 Too Many Requests	-	요청 제한을 초과했습니다.	API 호출 한도를 초과했습니다.
500 Internal Server Error	-	서버 내부 오류	서비스 점검 또는 시스템 오류로 인한 처리 불가

에러 발생 시, 응답은 다음과 같은 JSON 형식으로 반환됩니다. name 필드는 해당 에러의 코드를, message 필드는 오류와 관련된 메세지를 반환합니다. Quotation API는 정수 형식의 name 필드를, Exchange API는 문자열 형식의 name 필드를 반환합니다. 각 API 별 오류 예시는 API Reference 문서 우측 하단 응답 예시 영역을 참고하시기 바랍니다.

{
  "error": {
    "name": 400,
    "message": "ERROR_MESSAGE"
  }
}

{
  "error": {
    "name": "ERRPR_CODE",
    "message": "ERROR_MESSAGE"
  }
}

인코딩

GET 또는 DELETE API에 대해 쿼리 파라미터를 포함한 요청을 전송하는 경우 모든 쿼리 파라미터를 URL 인코딩 한 후 요청해야 합니다. 인코딩이 정상적으로 이루어지지 않은 요청에 대해 응답으로 400 Invalid parameter 에러가 발생할 수 있습니다. 단, Exchange API의 파라미터 중 배열 형식의 파라미터가 이름에 []를 포함하고 있는 경우, '[',']' 문자는 인코딩 대상에서 제외합니다.

URL 인코딩이란?

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

(예시) :은 인코딩 후 %3A로, +는 %2B로 변환

gzip 응답 지원

인코딩 옵션을 gzip으로 요청하여 REST API 응답을 gzip 압축된 형태로 수신할 수 있습니다. gzip 형식으로 요청 시 API를 통해 주고 받는 데이터 크기를 줄여 트래픽 비용 및 응답 시간을 절감할 수 있습니다. gzip 인코딩은 시세(Quotation) API만 지원합니다. gzip 옵션 사용 시 아래와 같이 헤더를 지정합니다.

Accept-Encoding: gzip

API Reference 예제 코드 안내

보다 쉬운 API 사용을 위해 각 API Reference 우측 상단에서 해당 API 호출을 위한 예제 코드를 제공합니다. Shell(cURL), Python, Java, Node.js의 네가지 도구/언어 예시를 제공하며 Java와 Node.js는 사용하는 HTTP 클라이언트 라이브러리에 따라 아래와 같이 세분화하여 제공합니다. (코드 박스 상단 아래 화살표를 클릭하여 라이브러리별 예제를 변경할 수 있습니다.)

Java - AsyncHttp, java.net.http, OkHttp, Unirest
Node.js - Axios, fetch, https

문서의 요청 쿼리 파라미터 및 본문(Body) 영역에서 각 파라미터의 값을 예시값 또는 임의의 값으로 입력할 수 있습니다. 입력된 값에 따라 우측 예제 코드 또한 실시간으로 변경됩니다.

거래 및 자산 관리(Exchange) API의 경우 인증 토큰을 생성하는 부분은 예제 코드에서 제외되어 있습니다. 인증문서의 인증 토큰 생성 예제 코드를 참고하여 실제 연동 시에는 반드시 인증 토큰을 요청에 포함하도록 구현해주시기 바랍니다.