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

Open API Beta Service in Upbit Thailand

The API endpoint for Thailand is currently in beta and may be subject to change. Any updates to the endpoint will be announced in advance via official announcements, so please keep this in mind when using the service.

The Upbit Open API supports only TLS version 1.2 or higher to ensure the security of your information. Versions below TLS 1.2 are no longer supported, so please upgrade to at least TLS 1.2.

- TLS 1.2 (Minimum supported version)
- TLS 1.3 (Recommended version)

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

Form-based POST requests are no longer supported from March 1, 2022.

Due to the end of Form support, POST requests sent using URL-encoded Form data are no longer guaranteed to work properly. Please ensure that the request body is sent strictly in JSON format.

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 HTTP status codes returned by the Upbit REST API and their meanings.

HTTP Status Code	Related Error Code	Reason	How to Resolve
200 OK	-	Successful response	-
201 Created	-	Resource created by request	-
400 Bad Request	`create_ask_error`, `create_bid_error`	Order request information is invalid.	This may occur if you set a price for a market order. Please refer to the order creation documentation.
	`insufficient_funds_ask`, `insufficient_funds_bid`	Insufficient funds for ask/bid.	Please check your available balance.
	`under_min_total_ask`, `under_min_total_bid`	Below minimum order amount.	Check the minimum order amount for the pair and try again.
	`withdraw_address _not_registered`	Unregistered withdrawal address.	Ensure the withdrawal address is included in your registered address list.
	`validation_error`	Invalid API request.	Check for missing required parameters.
401 Unauthorized	`invalid_query_payload`	Invalid JWT payload.	Please refer to the authentication documentation and check your token signature generation.
	`jwt_verification`	JWT verification failed.	Check the generation and signature of your token.
	`expired_access_key`	API key expired.	Issue and use a new API key.
	`nonce_used`	Nonce value already used.	You must use a unique nonce value for every JWT request.
	`no_authorization_ip`	Unauthorized IP address.	Ensure you are calling the API from an IP registered when the key was issued.
	`no_authorization_token`	Missing Auth Token.	Ensure that the Authorization header is included in the request.
	`out_of_scope`	Feature not permitted.	Check if the required feature is included when issuing your API key.
404 Not Found	-	Requested data does not exist.	This occurs if the requested order, withdrawal, deposit, or trade does not exist.
418 I'm a teapot	-	Request denied due to excessive requests.	Requests may be blocked due to IP restrictions, etc.
429 Too Many Requests	-	Rate limit exceeded.	You have exceeded your API call quota.
500 Internal Server Error	-	Internal server error	Request cannot be processed due to service maintenance or a system error.

When an error occurs, the response is returned in the following JSON format. The name field contains the error code, and the message field provides the related error message. The Quotation API returns the name field as an integer, while the Exchange API returns name it as a string. For error examples specific to each API, please refer to the response example sections located at the bottom right of the respective API Reference documentation.

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

{
  "error": {
    "name": "ERRPR_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.

What is the URL Encoding?

URL encoding is an encoding method that converts characters that cannot be included in a URL within a communication protocol into transmittable characters. Target characters, including special characters, are converted during encoding into a string consisting of a percent sign (%) followed by two hexadecimal digits.

(Example) : is encoded to %3A and + is encoded to %2B.

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.