업비트 API 에러코드 24개 — 재시도할 것과 멈출 것

이 글의 표와 메시지는 업비트 개발자 센터(docs.upbit.com)의 REST API 사용 및 에러 안내·요청 수 제한(Rate Limits)·주문 생성 레퍼런스와 REST API 연동 Best Practice 문서를 2026-10-03에 대조해 정리했습니다. 업비트 봇의 전체 구조는 허브 글 업비트 자동매매 — REST만 쓰면 절반은 손해본다에 있고, 이 글은 그중 "에러가 났을 때 봇이 무엇을 해야 하나" 하나만 다룹니다.

1. 에러 응답의 모양 — name이 숫자일 때와 문자열일 때

업비트는 에러가 나면 error 객체 안에 name과 message를 돌려줍니다. 함정은 API 종류에 따라 name의 타입이 다르다는 점입니다. 공식 문서는 시세 조회(Quotation) API는 정수, 거래·자산(Exchange) API는 문자열을 반환한다고 적고 있습니다.

// Quotation API (시세: /v1/ticker, /v1/candles ...) — name 이 정수
{
  "error": {
    "name": 400,
    "message": "ERROR_MESSAGE"
  }
}

// Exchange API (주문·잔고: /v1/orders, /v1/accounts ...) — name 이 문자열
{
  "error": {
    "name": "insufficient_funds_bid",
    "message": "주문 가능한 금액(KRW)이 부족합니다."
  }
}

비교 전에 str(err.get("name"))로 타입을 맞춰 두십시오.

또 하나, 공식 문서는 out_of_scope 항목에서 "API 도메인(포켓·입출금·주문)마다 HTTP 상태 코드(401, 403)가 일관되지 않을 수 있으니 에러코드 문자열 기준으로 검증하라"고 권장합니다. 상태코드 분기는 큰 묶음(4xx/5xx)에만 쓰고, 실제 대응은 error.name으로 정하라는 뜻입니다.

2. 업비트 API 에러코드 24개 전체표

공식 에러 안내 표(20개)에 POST /v1/orders 레퍼런스의 응답 예시에만 나오는 4개(invalid_time_in_force·over_krw_funds_bid·notfoundmarket·market_offline)를 더했습니다. 마지막 열이 봇이 할 일입니다.

3. 주문에서 가장 자주 나는 6개

① under_min_total_bid — 5,000원 미만

원화(KRW) 마켓의 최소 주문 가능 금액은 공식 문서 기준 5,000 KRW입니다(BTC·USDT 마켓은 별도 문서). 분할 매수 봇이 "잔고의 10%씩"처럼 비율로 금액을 정하면 잔고가 줄어든 뒤 어느 순간부터 이 에러가 반복됩니다. 주문 직전에 총액을 계산해 5,000원 미만이면 아예 보내지 않는 필터가 정답이고, 마켓별 최소값은 GET /v1/orders/chance 응답의 min_total로 확인할 수 있습니다.

② insufficient_funds_bid — 잔고가 있는데 부족하다고 할 때

주문 가능 금액은 GET /v1/accounts의 balance이고, 미체결 주문에 묶인 돈은 locked로 따로 잡힙니다. 지정가 매수를 걸어 둔 채 같은 원화로 또 매수하면 이 에러가 납니다. 매수 수수료(/v1/orders/chance의 bid_fee)도 총액에 더해져야 하므로, 잔고를 100% 쓰는 주문은 수수료만큼 모자라 거절되기 쉽습니다.

③ create_bid_error — 시장가 주문 파라미터 조합

공식 문서가 직접 드는 원인은 "시장가 주문임에도 가격을 입력하는 경우"입니다. 업비트의 시장가는 매수와 매도가 다른 ord_type을 씁니다.

④ invalid_time_in_force — post_only와 SMP

post_only는 ord_type=limit에서만 쓸 수 있고 smp_type과 함께 쓸 수 없습니다. ioc·fok는 지정가와 최유리 지정가에서 사용합니다. 자전거래 방지 옵션은 업비트 SMP 글에 정리해 두었습니다.

⑤ duplicated_identifier — 실패한 주문의 ID도 재사용 불가

identifier는 계정 내 전체 주문 기준으로 고유해야 하고, 생성·체결 여부와 관계없이 한 번 쓴 값은 다시 쓸 수 없으며 최대 64자입니다. 그래서 같은 identifier로 재전송하면 이중 주문 대신 이 에러가 나고, 첫 요청의 접수 여부는 identifier로 조회해 확인합니다.

⑥ 호가 단위 위반

원화 마켓은 가격 구간마다 주문 단위가 다릅니다(예: 10원 이상~100원 미만은 0.1원). 15원짜리 코인에 15.01원으로는 주문할 수 없다는 것이 공식 예시입니다. 이때의 error.name은 공식 표에 없으므로 주문 전에 가격을 tick_size(호가 정책 조회 API) 단위로 내림하고 실제 응답을 로그로 남기십시오.

4. 인증 에러 7개 — JWT·nonce·IP·권한

401 계열은 거의 전부 코드나 설정 문제라 재시도로 풀리지 않습니다. 공식 Best Practice 예제의 토큰 생성부는 이렇습니다.

import hashlib, uuid, jwt
from urllib.parse import urlencode, unquote

def make_token(access_key, secret_key, params=None):
    payload = {"access_key": access_key, "nonce": str(uuid.uuid4())}   # 요청마다 새 nonce
    if params:
        query_string = unquote(urlencode(params, doseq=True))         # 실제로 보내는 값과 같아야 함
        payload["query_hash"] = hashlib.sha512(query_string.encode("utf-8")).hexdigest()
        payload["query_hash_alg"] = "SHA512"
    token = jwt.encode(payload, secret_key, algorithm="HS512")
    return token if isinstance(token, str) else token.decode("utf-8")

• invalid_query_payload — query_hash를 만든 문자열과 실제로 보낸 파라미터가 다를 때가 대표적입니다. 해시를 만든 뒤 파라미터를 하나 더 붙이거나, 숫자를 float로 바꿔 "5000"이 "5000.0"이 되면 어긋납니다. 배열 파라미터는 이름의 []를 인코딩하지 않는다는 규칙도 공식 문서에 있습니다.
• jwt_verification — Secret Key가 틀렸거나 서명 과정이 깨진 경우. Access Key와 Secret Key를 뒤바꿔 넣는 실수가 흔합니다.
• nonce_used — 재시도 루프가 이미 만든 토큰을 재사용할 때 납니다. 재시도마다 make_token()을 다시 호출하십시오.
• no_authorization_ip — API 키는 등록한 IP에서만 쓸 수 있습니다. 클라우드 서버를 재시작해 공인 IP가 바뀌면 그 순간부터 모든 주문이 이 에러로 막힙니다. 클라우드 서버는 고정 IP를 쓰십시오.
• expired_access_key — 업비트 공지 기준 API 키 유효기간은 1년이고 연장할 수 없습니다. 만료 전 삭제·재발급이 유일한 방법이니 발급일을 봇 설정에 기록해 두고 30일 전 알림을 거는 것이 좋습니다.
• no_authorization_token — Authorization: Bearer {토큰} 헤더 누락.
• out_of_scope(403) — 조회 권한만 준 키로 주문을 보낸 경우. 키 권한은 포켓별 API Key 목록 조회로 확인할 수 있습니다. 키 관리 원칙은 API 키 보안 글에 있습니다.

5. 429·418·500 — 속도 제한과 차단

업비트는 모든 REST 응답 헤더에 그룹과 잔여 요청 수를 실어 보냅니다.

Remaining-Req: group=default; min=1800; sec=29

sec가 이번 1초에 남은 횟수이고, min은 공식 문서에서 Deprecated(참조하지 말 것)로 표시돼 있습니다. 그룹별 한도는 공식 Rate Limits 문서 기준으로 시세 그룹(market·candle·trade·ticker·orderbook) 각 초당 10회(IP 단위), default 초당 30회, order 초당 12회(2026-08-21에 8회에서 상향), order-test 초당 8회, order-cancel-all 2초당 1회입니다. 거래·자산 그룹은 2026-06-25부터 계정이 아니라 포켓 단위로 셉니다.

• 429 — 초당 한도 초과. 공식 대응은 "다음 초 경계까지 대기 후 재시도"입니다.
• 418 — 429를 받고도 계속 보낸 결과인 일시 차단입니다. 응답에 담긴 차단 시간이 지날 때까지 재시도하지 말아야 하고, 공식 문서는 위반이 반복되면 차단 시간이 점진적으로 늘어난다고 적고 있습니다.
• 500 — 서비스 점검 또는 시스템 오류. Best Practice는 5xx 같은 일시 장애는 호출 목적에 맞게 재시도할 수 있다고 안내합니다. 단, 주문 생성 요청의 500은 "접수됐는지 모르는 상태"이므로 재전송 전에 identifier로 조회부터 하십시오.

여러 거래소·증권사 봇에 공통으로 쓰는 스로틀 설계는 API 호출 제한 설계 글에 정리했습니다.

6. 봇의 분기 코드 — 재시도 / 중단 / 알림

위 표를 그대로 코드로 옮기면 이렇습니다. requests 기준이며, 알림 함수는 텔레그램 등 운영 중인 채널로 바꾸면 됩니다.

import time, requests

STOP = {  # 같은 요청을 다시 보내도 결과가 같은 에러 → 멈추고 사람에게 알림
    "create_ask_error", "create_bid_error",
    "insufficient_funds_ask", "insufficient_funds_bid",
    "under_min_total_ask", "under_min_total_bid", "over_krw_funds_bid",
    "invalid_time_in_force", "validation_error",
    "invaild_parameter", "invalid_parameter",          # 공식 문서 철자 두 가지
    "duplicated_identifier", "notfoundmarket",
    "invalid_query_payload", "jwt_verification", "expired_access_key",
    "no_authorization_ip", "no_authorization_token", "out_of_scope",
}

def call(method, url, make_headers, max_retry=3, **kw):
    for attempt in range(max_retry):
        r = requests.request(method, url, headers=make_headers(), timeout=5, **kw)  # 매번 새 토큰
        if r.ok:
            return r.json()
        if r.status_code == 418:
            raise SystemExit("418 일시 차단 — 차단 시간까지 봇 전체 정지: " + r.text)
        if r.status_code == 429:
            time.sleep(1.0 - (time.time() % 1.0) + 0.05)   # 다음 초 경계까지
            continue
        name = str((r.json().get("error") or {}).get("name", ""))
        if name in STOP:
            notify(f"[업비트] {r.status_code} {name} — 재시도 안 함: {r.text}")
            return None
        if name == "nonce_used" or name == "market_offline" or r.status_code >= 500:
            time.sleep(0.5 * (2 ** attempt))
            continue
        notify(f"[업비트] 미분류 에러 {r.status_code} {name}")
        return None
    notify(f"[업비트] 재시도 {max_retry}회 실패: {url}")
    return None

핵심은 make_headers를 함수로 넘겨 재시도마다 토큰을 새로 서명하는 것(nonce_used 방지)과, 418을 예외로 올려 봇 전체를 세우는 것입니다. 장애 상황별 복구 순서는 봇 장애 복구 플레이북을 함께 보십시오.

7. 실주문 전에 걸러내기 — /v1/orders/test 와 /v1/orders/chance

업비트는 모의투자 서버가 없는 대신 주문 생성 테스트 API(POST /v1/orders/test)를 제공합니다. 공식 설명은 "실제 주문과 동일한 검증 과정을 거치지만 주문이 실제로 생성되지는 않는다"이고, 수수료도 들지 않습니다. 위 400 계열 에러 대부분을 실돈 없이 미리 확인할 수 있다는 뜻입니다.

POST https://api.upbit.com/v1/orders/test
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{"market": "KRW-BTC", "side": "bid", "ord_type": "price", "price": "4000"}
# → 원화 마켓 최소 5,000 KRW 미달이면 under_min_total_bid 가 이 단계에서 걸린다

• 테스트 응답의 uuid·identifier는 조회·취소에 쓸 수 없습니다(실제 주문이 아니므로).
• order-test 그룹은 초당 8회로 실주문(order 12회)과 한도를 따로 셉니다.
• 마켓별 최소·최대 주문 금액(min_total·max_total)과 수수료(bid_fee·ask_fee)는 GET /v1/orders/chance?market=KRW-BTC로 받아 두고, 봇 시작 시 한 번 캐시하는 구성이 깔끔합니다.

업비트 봇을 처음 만든다면 파이썬 업비트 봇 30분에서 기본 골격을, 취소·정정 흐름은 업비트 취소 후 재주문 API에서 이어서 볼 수 있습니다. 증권사 쪽 에러 체계와 비교하고 싶다면 KIS API 에러코드 정리가 같은 구조로 되어 있습니다.

8. 자주 묻는 질문