out_of_scope는 요청에 사용한 API Key에 지금 호출한 기능의 권한이 없다는 뜻입니다. HTTP 401·403만으로 원인을 정하지 말고 응답의 error.name을 확인하세요. 그다음 현재 Key의 권한과 호출한 API 문서 하단의 API Key Permission을 대조합니다. 필요한 권한이 없다면 모든 권한을 켜지 말고, 그 기능에 필요한 최소 권한만 포함한 Key로 교체합니다.
2026년 9월 20일 업비트 REST API 오류표와 인증·포켓별 API Key·주문·출금 공식 문서를 확인했습니다. 실계정 Key 목록 조회나 권한 변경은 실행하지 않았고, 정확 월간 검색량과 실제 독자 질문은 미확인입니다.
목차
1. HTTP 상태보다 error.name을 먼저 보세요
업비트 REST API 공식 오류표는 API 도메인에 따라 HTTP 401과 403이 일관되지 않을 수 있으므로, 예외 처리는 상태 코드보다 오류 문자열을 기준으로 하라고 안내합니다. 응답 본문에서 error.name이 정확히 out_of_scope인지 먼저 확인하세요.
아래 오류는 조치가 다릅니다.
| 오류 | 먼저 볼 것 | 다음 행동 |
|---|---|---|
out_of_scope |
현재 Key의 기능 권한 | 호출 API의 요구 권한과 대조 |
expired_access_key |
Key 만료 여부 | 만료 Key를 삭제하고 새 Key로 교체 |
no_authorization_ip |
실제 요청 출발 공인 IPv4 | 해당 Key의 허용 IP와 대조 |
jwt_verification |
Access·Secret Key 쌍과 JWT 서명 | 토큰 생성 과정 점검 |
open_api_withdraw_locked |
해당 Key의 출금 안심차단 | 모바일 앱에서 별도 조건 확인 |
좌우로 밀어 표를 비교하세요.
2. 현재 Key 권한을 확인하세요
먼저 프로그램이 실제로 읽는 Access Key의 식별값과 확인 중인 Key가 같은 발급 건인지 대조합니다. Secret Key는 출력하거나 로그에 남기지 마세요.
포켓 기능을 쓰고 있고 메인포켓의 포켓관리 권한이 있는 Key라면 포켓별 API Key 목록 조회 공식 문서의 API로 포켓별 Key 목록을 조회할 수 있습니다.
GET https://api.upbit.com/v1/pockets/api_keys
공식 문서가 표시하는 Key 정보는 다음과 같습니다.
access_key: 어떤 Key인지 식별permissions: 현재 부여된 권한allowed_ips: 허용 IPcreated_at: 생성 시각expired_at: 만료 시각
include_expired의 기본값은 false입니다. 만료 Key까지 대조하려면 이 조건을 별도로 확인해야 합니다.
이 목록 API는 모든 Key가 바로 호출할 수 있는 범용 조회 방법이 아닙니다. 메인포켓만 사용할 수 있고, 조회에 쓰는 Key에도 포켓관리 권한이 필요합니다. 목록 조회에서 다시 out_of_scope가 나오면 원래 기능 권한이 아니라 목록 조회용 포켓관리 권한부터 구분하세요.
이 조건이 없으면 다음 순서로 확인합니다.
- PC 브라우저에서 업비트에 로그인합니다.
마이페이지 → Open API 관리로 이동합니다.- 현재 프로그램이 쓰는 Access Key와 같은 발급 건을 찾고 선택된 기능 권한을 확인합니다. Secret Key는 표시·복사·캡처하지 마세요.
- 현재 Key에 필요한 권한이 없으면 업비트 API Key 발급 공식 가이드와 같은 화면에서 필요한 기능만 선택한 새 Key를 발급합니다.
로그인이나 계정 조건에서 막히면 업비트 공식 고객센터에서 Open API 안내를 확인하세요.
3. 호출 기능과 요구 권한을 맞추세요
업비트 인증 가이드의 API Key 권한 그룹표는 조회와 실행 권한을 따로 나눕니다. 이름이 비슷해도 같은 권한이라고 가정하면 안 됩니다.
| 하려는 일 | 필요한 권한 그룹 | 공식 문서의 대표 기능 |
|---|---|---|
| 포켓 잔고 확인 | 자산조회 |
포켓 잔고 조회 |
| 주문을 실제 생성·취소 | 주문하기 |
주문 생성, 주문 생성 테스트, 주문 취소 |
| 주문 상태·가능 조건 확인 | 주문조회 |
주문 가능정보, 단일·목록·대기·종료 주문 조회 |
| 출금을 요청·취소 | 출금하기 |
디지털 자산·원화 출금, 디지털 자산 출금 취소 |
| 출금 상태·허용 주소 확인 | 출금조회 |
출금 가능 정보, 허용 주소, 단일·목록 조회 |
| 원화 입금·트래블룰 검증 요청 | 입금하기 |
원화 입금, UUID·TXID 트래블룰 검증 요청 |
| 입금 주소·입금 상태 확인 | 입금조회 |
입금 주소 생성·조회, 입금 목록, 지원 거래소 조회 |
좌우로 밀어 표를 비교하세요.
예를 들어 GET /v1/orders/chance 공식 문서는 주문을 만들지 않지만 주문조회 권한을 요구합니다. 반면 POST /v1/orders/test 공식 문서는 실제 주문을 생성하지 않는 테스트 API여도 주문하기 권한을 요구합니다. API 이름의 ‘조회’나 ‘테스트’만 보고 권한을 추정하지 말고, 호출한 엔드포인트 문서의 API Key Permission 문구를 직접 확인해야 합니다.
4. 필요한 최소 권한으로 교체하세요
- 실패한 요청의 메서드와 경로를 기록합니다. 쿼리값·JWT·Secret Key는 기록하지 않습니다.
- 해당 API Reference 하단에서 필요한 권한 그룹을 확인합니다.
- 현재 Key의
permissions또는 관리 화면의 권한과 대조합니다. - 권한이 빠졌다면 그 Key를 사용하는 다른 프로그램과 작업을 먼저 확인합니다.
- 필요한 최소 권한만 선택한 Key로 교체하고 Access·Secret Key 쌍을 함께 바꿉니다.
- 조회 요청이나 실제 자산 이동이 없는 검증 요청부터 호출해
out_of_scope가 사라졌는지 확인합니다. - 주문·입금·출금은 각 기능의 별도 조건까지 확인한 뒤 단계적으로 검증합니다.
권한을 전부 추가하면 당장 오류가 사라질 수 있어도 Key 노출 시 허용 범위도 함께 커집니다. 오류가 난 기능 한 가지와 필요한 권한 한 가지를 먼저 맞추는 편이 안전합니다.
주문과 출금은 추가 조건이 남습니다
out_of_scope가 사라졌다는 사실은 요청이 최종 성공했다는 뜻이 아닙니다.
- 주문:
POST /v1/orders/test는 실제 주문 없이 요청 형식과 주문 가능 여부를 확인하지만, 그 자체에도주문하기권한이 필요합니다. - 출금:
출금하기권한이 있어도 출금 안심차단이 적용돼 있으면 출금 API를 사용할 수 없습니다. 이때는 업비트 Open API 출금 안심차단 해제를 따로 확인하세요. - 공통: 허용 IP, JWT 서명, Key 만료 등은 각각 다른 오류로 남을 수 있습니다.
따라서 권한 수정 뒤에는 상태 코드만 보지 말고 새 응답의 error.name 또는 정상 응답을 다시 확인하세요.
확인 순서만 짧게 정리하면
error.name이 out_of_scope인가
→ 실제 사용 중인 Key가 맞는가
→ 현재 permissions는 무엇인가
→ 호출 API의 API Key Permission은 무엇인가
→ 필요한 최소 권한의 Key로 교체했는가
→ 위험이 낮은 요청부터 실제 응답을 확인했는가
실계정 권한과 Key 교체 결과는 계정마다 직접 확인해야 합니다. 이 글은 정보 제공 목적이며 가상자산 투자 권유나 자문이 아닙니다.
돈 문제를 판단할 때 필요한 새 소식
청약·세금·대출의 바뀐 조건과 공식 확인 경로를 정리한 이메일을 준비하고 있습니다. 발송을 시작하면 안내해 드려요. 먼저 확인 메일에서 본인 이메일을 확인해 주세요.
신청하기 전에 첫 소식 미리보기에서 내용과 자료를 확인해 보세요.