REST API Usage and Error Guide

Endpoint

Upbit Singapore: https://sg-api.upbit.com

Upbit Indonesia: https://id-api.upbit.com

Upbit Thailand: https://th-api.upbit.com

Content Type

Upbit REST API supports the application/json content type. In particular, for POST requests, the request body must be in JSON format, and the following header should be included:

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

Authentication

For authenticated Exchange API requests, you must include a JWT token generated according to the Authentication guide in the Authorization header. Upbit REST API supports Bearer authentication, and the header should be set as follows:

Authorization: Bearer eyJhb...d8sTw

Rate Limits

Please refer to the Rate Limits document for the REST API request rate limit policy.

Response Status Codes and Error Information

The following table lists the main HTTP status codes returned by the Upbit REST API and their meanings.

400 Bad Request

This error occurs when the request format or parameters are invalid.

401 Unauthorized

This error occurs when authentication using a JWT token, API Key, or authorized IP address fails.

403 Forbidden

This error occurs when a request is not permitted due to API Key permissions or Open API security restrictions.

Depending on the API domain, the out_of_scope error may be returned with either HTTP 401 Unauthorized or 403 Forbidden.

When handling API errors, check the error.name field in the response body in addition to the HTTP status code.

404 Not Found

This error occurs when the requested resource does not exist or cannot be retrieved.

418 I'm a teapot

This error occurs when requests are restricted due to repeated excessive API calls.

429 Too Many Requests

This error occurs when the permitted API request rate limit is exceeded.

500 Internal Server Error

This error occurs when the server cannot process a request due to an internal error.

Error Response Format

When an error occurs, the API returns a JSON response containing the following fields:

• error.name: The error code.
• error.message: A message describing the error.

The Quotation API returns error.name as an integer, while the Exchange API returns it as a string.

For API-specific error examples, refer to the response example section at the bottom right of each API Reference page.

Quotation API Error Response

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

Exchange API Error Response

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

Encoding

When sending a GET or DELETE API request that includes query parameters, all query parameters must be URL-encoded before sending the request. If the request is not properly URL-encoded, the server will return a 400 Invalid parameter Response. However, if an array-type parameter in the Exchange API includes [] in its name, the "[" and "]" characters must be excluded from URL encoding.

gzip Response Support

You can receive REST API responses in gzip-compressed format by specifying the Accept-Encoding: gzip header in your request. Using gzip encoding reduces the size of data transferred between the server and client, which helps save traffic costs and decrease response times. gzip encoding is only supported by Quotation APIs. To enable gzip, set the following header in your request:

Accept-Encoding: gzip

API Reference Example Code Guide

To make API usage easier, example code snippets are provided at the top right of each API Reference page. Examples are available for four environments/languages: Shell (cURL), Python, Java, and Node.js. For Java and Node.js, examples are provided for multiple popular HTTP client libraries, which you can switch between using the dropdown arrow above the code block:

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

You can input sample or custom values for each request parameter and body field in the documentation. The example code will update in real-time based on your inputs.

Note: For Exchange APIs (such as trading or asset management), the authentication token part is not included in the example code. Please refer to the Authentication documentation for JWT token generation examples. You must implement token creation and include the resulting token in your requests when integrating with these APIs.