퍼프 주문 거부 사유 코드
주문 양식에 주문이 "거부될 것"이라고 표시되면, 이는 **사유 코드(reason code)**를 그대로 보여주는 것입니다. 서명 전에 실행되는 실시간 확인(미리보기)과 실제 제출에서 동일한 코드가 반환되므로, 양식에 표시되는 내용이 곧 서버가 처리할 결과입니다.
양식에서 사유 코드를 사용하는 방식:
- 차단 코드는 주문을 변경할 때까지 제출 버튼을 사유 문구(예:
Not enough margin)로 바꿉니다. - 새로고침 코드(
stale_position_snapshot,venue_risk_unavailable)는 자동으로 다시 확인되며 버튼을 차단하지 않습니다. - 재시도 후 차단 코드(
price_unavailable,account_health_unavailable)도 자동으로 다시 확인되지만, 확인을 통과할 때까지 버튼을 차단합니다. - 미리보기 실패는 주문을 차단하지 않습니다. 미리보기에 연결할 수 없으면 양식에 수치가 표시되지 않지만 주문은 제출할 수 있습니다. 실제 확인은 제출 시 그대로 실행됩니다.
invalid_order,engine_rejected및 알 수 없는 코드는 버튼을 차단하고 서버 메시지를 그대로 표시합니다. 해당 메시지에 실패한 필드나 규칙이 명시되어 있기 때문입니다.
API 사용자는 POST /v1/tee-perp/preview와 주문, 일괄 주문, 레버리지 제출 응답의 reasonCode에서 동일한 값을 받습니다. 사람이 읽을 수 있는 텍스트(미리보기의 reason, 제출 응답의 message)는 진단용이므로, 분기 처리는 코드 기준으로 하십시오.
증거금 및 포지션
| 코드 | 의미 | 해결 방법 |
|---|---|---|
insufficient_margin | 이 주문(및 모든 미체결 퍼프 주문)이 체결된 후 계정이 증거금 요건을 충족하지 못합니다. 증거금 요건은 Hypercall 포트폴리오 증거금과 Hyperliquid 증거금 중 더 큰 값입니다. | 양식에 표시되는 카드를 사용하십시오. Use max(통과 가능한 최대 수량), Raise to N×(통과 가능한 최소 레버리지), 또는 부족분 Deposit. 대기 중인 주문을 취소해도 증거금이 확보됩니다. |
reduce_only_exceeds_position | 감소 전용(reduce-only) 주문이 포지션을 줄이는 대신 늘리거나 반대 방향으로 전환합니다. | 수량을 보유 포지션 이하로 설정하거나(양식에서 Use position 제공), Reduce only를 해제하십시오. |
mode_change_with_position | 포지션을 보유한 마켓에서 교차(cross)와 격리(isolated) 모드를 전환하려고 했습니다. Hyperliquid에서도 허용되지 않습니다. | 현재 모드를 유지하거나, 포지션을 청산한 후 전환하십시오. |
leverage_requires_flat_account | 계정에 퍼프 포지션 또는 대기 중인 퍼프 주문이 있어 레버리지 변경이 거부되었습니다. 이는 Hypercall이 증거금에 Hyperliquid 강제청산 리스크를 반영하지 않는 환경에서만 발생합니다. 프로덕션은 이를 반영하므로 프로덕션에서는 이 코드가 반환되지 않습니다. | 포지션을 청산하고 퍼프 주문을 취소한 후 레버리지를 변경하십시오. |
liquidation_pending | 계정이 사전 청산 상태이며 전체 강제청산이 곧 시작됩니다. Hypercall은 해당 계정의 신규 퍼프 주문을 거부합니다. | 강제청산이 처리될 때까지 기다리십시오. 강제청산을 참고하십시오. |
계정 설정
| 코드 | 의미 | 해결 방법 |
|---|---|---|
account_not_pm | 퍼프 주문에는 포트폴리오 증거금 계정이 필요합니다. | 계정 페이지에서 포트폴리오 증거금을 켠 후 다시 시도하십시오. |
unified_mode_required | 리스크를 늘리는 주문은 트레이딩 계정에서 Hyperliquid 통합 계정(unified account) 모드가 필요합니다. | 양식에서 Enable unified mode를 클릭하십시오. |
builder_not_approved | 계정이 Hypercall의 빌더 주소를 승인하지 않아 Hyperliquid가 주문을 거부했습니다. 이 코드는 미리보기가 아니라 제출 시 Hyperliquid에서 반환되며, API 사용자는 reasonCode가 아닌 제출 응답의 errorCode에서 확인할 수 있습니다. | Enable trading을 한 번 클릭하십시오. Hypercall의 퍼프를 참고하십시오. |
account_health_unavailable | Hypercall이 현재 계정의 증거금 상태를 읽을 수 없어 리스크를 늘리는 모든 주문을 거부합니다. | 양식이 자동으로 다시 확인합니다. 그동안 리스크를 줄이려면 Reduce only를 켠 상태로 주문을 보내십시오. |
마켓 및 데이터
| 코드 | 의미 | 해결 방법 |
|---|---|---|
market_not_supported | Hypercall이 리스크를 산정할 수 없는 마켓입니다. 가격 피드, 증거금 시나리오 그리드, 그리고 해당 계정에 대한 USDC 증거금 기반 Hyperliquid 스케줄이 필요합니다. | 지원되는 마켓을 선택하십시오. |
trading_halted | 전체 또는 해당 마켓의 거래가 일시 중지되었습니다. | 기다리십시오. 거래가 재개될 때까지 양식이 버튼을 비활성화 상태로 유지합니다. |
price_unavailable | Hypercall이 마켓 가치 평가에 사용하는 가격이 없거나 오래되었습니다. | 양식이 자동으로 다시 확인합니다. Hypercall은 가격을 추정하지 않으므로 새 가격이 들어올 때까지 거부합니다. |
stale_position_snapshot | 최신 Hyperliquid 포지션 또는 자산(equity) 정보가 없거나 너무 오래되었습니다. | 별도 조치가 필요 없습니다. 양식이 한 번 자동으로 다시 확인합니다. 계속되면 새로고침하십시오. |
venue_risk_unavailable | Hyperliquid 리스크 정보(레버리지, 강제청산 가격, 포지션별 담보)가 없거나 최신 포지션 정보와 일치하지 않습니다. | 별도 조치가 필요 없습니다. 양식이 한 번 자동으로 다시 확인합니다. |
주문 조건
| 코드 | 의미 | 해결 방법 |
|---|---|---|
invalid_order | 주문 조건이 유효하지 않습니다. 가격 또는 수량 정밀도, 잘못된 형식의 TP/SL 브래킷, 또는 잘못된 클라이언트 주문 ID가 원인입니다. | 가격 틱 또는 수량 단위를 수정한 후 다시 제출하십시오. |
action_not_supported | 서명 엔클레이브의 정책이 이 유형의 작업을 허용하지 않습니다. 양식에서 제공하는 주문 유형에서 발생하면, 양식은 해당 유형을 활성화되지 않음으로 표시합니다. | 지원되는 주문 유형을 사용하십시오. |
engine_rejected | 그 밖의 모든 거부입니다. reason 텍스트에 정확한 원인이 담겨 있습니다. | 메시지를 확인하십시오. 내용이 불분명하면 해당 텍스트와 함께 고객지원에 문의하십시오. |