이 페이지는 자동 번역되었습니다. 영어 원문이 정본입니다. 영어로 읽기 →
메인 콘텐츠로 건너뛰기

오류 및 거부 사유

오류 코드와 거부 사유의 전체 카탈로그입니다.

오류 응답 형식​

HTTP 오류 응답 (미들웨어)​

미들웨어에서 반환되는 구조화된 JSON 오류입니다 (HTTP 4xx/5xx):

{
  "error": "<code>",
  "message": "<human message>"
}

엔진 수준 거부 (HTTP 200)​

거래 거부는 HTTP 200과 함께 OrderUpdateMessage.status = "REJECTED"를 반환합니다:

{
  "timestamp": 1735000000000,
  "info": { ... },
  "status": "REJECTED",
  "reason": "<exact rejection string>",
  "filled_size": 0,
  "order_id": null,
  "wallet_address": "0x...",
  "mmp_triggered": false
}

중요: 거래 거부 여부를 HTTP 상태 코드에 의존하지 마십시오. 항상 status와 reason 필드를 확인하십시오.

미들웨어 오류 코드​

다음은 구조화된 JSON 본문과 함께 HTTP 오류 응답으로 반환됩니다.

코드HTTP 상태설명
invalid_request400요청 본문을 읽을 수 없음
invalid_json400JSON 파싱 실패
missing_field400필수 필드 누락
invalid_wallet400지갑 문자열을 파싱할 수 없음
invalid_parameter400잘못된 파라미터 (예: size/price는 문자열이어야 함)
signature_verification_failed400EIP-712 서명 복구 실패
unsupported_endpoint400미들웨어가 이 경로를 지원하지 않음
unauthorized401서명자가 지갑에 대한 권한이 없음 (에이전트 인증 실패)
internal_error500에이전트 권한 확인이 예기치 않게 실패함

엔진 거부 사유​

다음은 status="REJECTED"일 때 OrderUpdateMessage.reason에 나타납니다.

만기된 상품​

사유: "Instrument has expired"

원인: 이미 만기된 상품에 주문이 접수되었습니다.

조치: GET /instruments 또는 GET /markets를 통해 상품 만기를 확인하십시오.

자금 미입금 계정​

사유: "Account has no funds. Please deposit before trading."

원인: 계정 현금 잔고가 <= 0.0입니다.

조치: 거래 전에 지갑에 USDC를 입금하십시오.

증거금 부족​

사유: "Insufficient margin: required={:.2}, available={:.2}, shortfall={:.2}"

예시: "Insufficient margin: required=1500.00, available=1200.00, shortfall=300.00"

원인: 거래 전 증거금 검사에서 제안된 주문 이후의 증거금 요건을 충족하기에 가용 담보(순자산)가 부족한 것으로 확인되었습니다.

Standard Margin 계정의 경우, 필요한 담보는 옵션 방향, 옵션 유형, 행사가격, 기초자산 가격 및 현재 포트폴리오에 따라 달라집니다. 현재 출시 증거금 모델은 Standard Margin을 참조하십시오.

조치:

  1. GET /portfolio?wallet=...를 통해 포트폴리오를 확인하십시오
  2. Margin에서 증거금 계산을 검토하십시오
  3. 포지션 크기를 줄이거나 담보를 추가하십시오

현물 가격 누락​

사유: "Failed to get portfolio: No spot price available for underlying: {underlying}"

원인: 엔진이 체결 시뮬레이션에 필요한 기초자산의 현물 가격을 추론할 수 없습니다.

조치: Hyperliquid 현물 가격 피드 연결 상태를 확인하십시오. 현물 가격은 allMids WebSocket 피드에서 제공됩니다.

티어 제한​

사유: "Tier1 users cannot go short. Filled long position: {filled}, total sell orders (including new): {total} (symbol: {symbol})"

원인: 지갑이 tier1(롱 전용)인데 충분한 체결된 롱 포지션 없이 매도를 시도했습니다.

조치:

  1. GET /user-tier?wallet=...를 통해 티어를 확인하십시오
  2. 모든 매도가 체결된 롱 포지션으로 커버되는지 확인하십시오
  3. 마켓메이커 연동을 위한 매도(writer) 권한이 필요한 경우 Hypercall에 문의하십시오

잘못된 심볼​

사유: "Invalid symbol: {symbol}"

원인: 해당 심볼에 대한 호가창이 존재하지 않습니다.

조치:

  1. GET /instrument-specs와 GET /markets를 통해 시장이 존재하는지 확인하십시오
  2. 심볼 형식을 확인하십시오: UNDERLYING-YYYYMMDD-STRIKE-(C|P)

심볼 파싱 오류​

사유: "Failed to parse symbol: {detail}"

원인: 심볼이 예상 형식과 일치하지 않습니다.

조치: 심볼 형식이 UNDERLYING-EXPIRY-STRIKE-(C|P) 또는 Deribit 스타일의 DDMMMYY와 일치하는지 확인하십시오.

취소 실패​

주문을 찾을 수 없음​

사유: "Order not found for cancellation: {client_id}"

원인: 주어진 client_id에 해당하는 주문을 찾을 수 없습니다.

조치: client_id가 올바른지, 그리고 GET /orders?wallet=...를 통해 주문이 존재하는지 확인하십시오.

호가창을 찾을 수 없음​

사유: "Orderbook not found for symbol: {symbol}"

원인: 해당 심볼에 대한 호가창이 존재하지 않습니다.

조치: 심볼이 유효하고 시장이 존재하는지 확인하십시오.

주문이 호가창에 없음​

사유: "Order {id} not found in orderbook {symbol}"

원인: 주문 ID는 존재하지만 주문이 호가창에 없습니다 (체결 또는 취소되었을 수 있음).

조치: GET /orders?wallet=...를 통해 주문 상태를 확인하십시오.

이미 체결된 주문​

사유: "Order {id} is already filled and cannot be cancelled"

원인: 취소 요청 전에 주문이 전량 체결되었습니다.

조치: GET /orders?wallet=...를 통해 주문 상태를 확인하십시오.

이미 취소된 주문​

사유: "Order {id} was already cancelled"

원인: 주문이 이미 취소되었습니다.

조치: GET /orders?wallet=...를 통해 주문 상태를 확인하십시오.

무기한 계약 주문 검증​

사유: "Perp order missing underlying symbol"

원인: 무기한 계약 주문에 underlying 필드가 포함되어 있지 않습니다.

조치: 무기한 계약 주문에 underlying 심볼이 포함되어 있는지 확인하십시오.

MMP 발동​

사유: "MMP triggered during fill processing"

원인: 체결 처리 중 MMP 한도를 초과했습니다. 주문이 부분 체결된 후 MMP가 발동되어 남은 수량이 취소되었습니다.

조치:

  1. GET /mmp-config?wallet=...&currency=...를 통해 MMP 설정을 확인하십시오
  2. 체결 윈도우 지표를 검토하십시오
  3. MMP 한도를 조정하거나 POST /mmp-config/reset을 통해 MMP 상태를 초기화하십시오

전체 MMP 동작 방식은 MMP를 참조하십시오.

MMP 취소 (다른 주문)​

사유: "Order canceled by MMP trigger"

원인: 동일한 지갑+기초자산에 대한 다른 주문이 MMP를 발동시켜 주문이 취소되었습니다.

조치: MMP 설정과 체결 활동을 검토하십시오.

핸들러 수준 검증 오류​

다음은 엔진에 도달하기 전에 HTTP 400을 반환합니다.

가격 검증​

오류: "Price validation failed: Price {price} has {n} significant figures, maximum allowed is 5"

원인: 가격이 유효숫자 5자리를 초과합니다.

조치: 가격을 유효숫자 5자리 이하로 반올림하십시오.

수량/가격 형식​

오류: "Size must be greater than 0" 또는 "Price must be greater than 0"

원인: 수량 또는 가격이 <= 0이거나 부동소수점으로 파싱할 수 없습니다.

조치: size와 price가 유효한 양수(문자열 형태)인지 확인하십시오.

잘못된 심볼 형식​

오류: 핸들러 오류 메시지와 함께 HTTP 400

원인: 심볼이 유효한 옵션 심볼로 파싱되지 않습니다.

조치: 심볼 형식을 확인하십시오: UNDERLYING-YYYYMMDD-STRIKE-(C|P).

대량 주문 오류​

대량 주문 엔드포인트는 BulkOrderResult.error에 항목별 오류를 반환합니다:

  • "Signature verification failed: ..."
  • "Unauthorized: signer not authorized for wallet"
  • "Price validation failed: ..."
  • "Size must be greater than 0"
  • "Price must be greater than 0"
  • "Failed to send order to engine"
  • "No response from engine"

각 결과에는 index(요청 배열에서의 위치)와 success 불리언이 포함됩니다.

WebSocket 오류​

WebSocket 제어 메시지:

{
  "type": "Error",
  "message": "Authentication required for this channel"
}

일반적인 오류:

  • "Authentication required for this channel": ?wallet= 없이 비공개 채널 구독을 시도함
  • "Client not found": 내부 오류 (연결 끊김)

오류 처리 모범 사례​

  1. 항상 status 필드를 확인하십시오: 거래 거부 여부를 HTTP 상태 코드에 의존하지 마십시오
  2. reason 문자열을 파싱하십시오: 프로그래밍 방식 처리에는 정확한 사유 문자열을 사용하십시오
  3. 대량 주문 오류를 처리하십시오: 대량 요청의 각 항목에 대해 BulkOrderResult.error를 확인하십시오
  4. 재시도 로직: REJECTED 주문은 재시도하지 마십시오 (먼저 근본 원인을 해결하십시오)
  5. 로깅: 거부 디버깅을 위해 전체 OrderUpdateMessage를 로깅하십시오

오류 코드 참조 표​

거부 사유분류HTTP 상태조치
Instrument has expired만기200만기 확인, 다른 상품 사용
Account has no funds...자금200자금 입금 (구현 시)
Insufficient margin: ...증거금200수량 축소, 담보 추가, 포트폴리오 확인
Failed to get portfolio: No spot price...데이터200Hyperliquid 피드 연결 확인
Tier1 users cannot go short...티어200tier2로 업그레이드 또는 매도 커버
Invalid symbol: ...심볼200시장 존재 여부 확인
Order not found for cancellation: ...취소200주문 존재 여부 확인
Order {id} is already filled...취소200주문이 이미 체결됨
Order {id} was already cancelled취소200주문이 이미 취소됨
MMP triggered during fill processingMMP200MMP 설정 검토, 한도 조정
Order canceled by MMP triggerMMP200MMP 설정 검토, 한도 조정
signature_verification_failed인증400서명, 문자열 인코딩 확인
unauthorized인증401에이전트 승인 또는 지갑으로 서명
Price validation failed: ...검증400가격을 유효숫자 5자리 이하로 반올림

거부 디버깅​

  1. 주문 상세 확인: symbol, price, size, side가 올바른지 확인하십시오
  2. 포트폴리오 확인: GET /portfolio?wallet=...로 현재 포지션과 현금을 확인하십시오
  3. 티어 확인: GET /user-tier?wallet=...로 티어 제한을 확인하십시오
  4. MMP 확인: GET /mmp-config?wallet=...&currency=...로 MMP 한도를 검토하십시오
  5. 시장 확인: GET /markets와 GET /instruments로 상품이 존재하는지 확인하십시오
  6. 로그 검토: 서버 로그에 추가 컨텍스트가 포함되어 있을 수 있습니다 (API를 통해 노출되지 않음)

참고​

  • 거부 로직: 거래 엔진에서 적용됩니다
  • 증거금 검사: 주문 접수 전에 적용됩니다
  • 티어 검사: 지갑 티어별로 적용됩니다
  • 핸들러 검증: 표준 요청 검증
최종 업데이트: