REST API 사용 및 에러 안내

Endpoint

https://api.upbit.com/v1

TLS

업비트 Open API는 회원님의 정보를 안전하게 보호하기 위해 TLS 1.2 이상 버전만 지원합니다.
TLS 1.2 미만 버전은 더 이상 지원되지 않으므로, 최소 TLS 1.2 이상으로 업그레이드해 주시기 바랍니다(TLS 1.3 권장 버전).

Content Type

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

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

인증

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

Authorization: Bearer eyJhb...d8sTw

요청 수 제한

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

응답 상태 코드 및 에러 안내

업비트 REST API에서 반환하는 주요 HTTP 상태 코드와 의미는 다음과 같습니다.

400 Bad Request

요청 형식이나 파라미터가 올바르지 않은 경우 발생합니다.

401 Unauthorized

JWT 토큰, API Key 또는 허용 IP 인증에 실패한 경우 발생합니다.

403 Forbidden

API Key 권한 또는 Open API 보안 설정으로 인해 요청이 허용되지 않은 경우 발생합니다.

404 Not Found

요청한 리소스가 존재하지 않거나 조회할 수 없는 경우 발생합니다.

418 I'm a teapot

과도한 요청이 반복되어 요청이 제한된 경우 발생합니다.

429 Too Many Requests

허용된 요청 수 제한을 초과한 경우 발생합니다.

500 Internal Server Error

서버 내부 오류로 요청을 처리할 수 없는 경우 발생합니다.

에러 응답 형식

에러가 발생하면 다음과 같은 JSON 형식으로 응답이 반환됩니다.

• error.name: 에러 코드
• error.message: 에러와 관련된 메시지

시세(Quotation) API는 정수 형식의 name 값을 반환하며, 거래 및 자산 관리(Exchange) API는 문자열 형식의 name 값을 반환합니다.

각 API의 상세 오류 예시는 API Reference 문서 우측 하단의 응답 예시 영역에서 확인할 수 있습니다.

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

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

에러 발생 시, 응답은 다음과 같은 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의 파라미터 중 배열 형식의 파라미터가 이름에 []를 포함하고 있는 경우, '[',']' 문자는 인코딩 대상에서 제외합니다.

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의 경우 인증 토큰을 생성하는 부분은 예제 코드에서 제외되어 있습니다. 인증문서의 인증 토큰 생성 예제 코드를 참고하여 실제 연동 시에는 반드시 인증 토큰을 요청에 포함하도록 구현해주시기 바랍니다.