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

API 오류

요청에 맞는 응답 형식을 사용하십시오.

  • HTTP 실패: 4xx 또는 5xx JSON 응답에는 안정적인 code 필드와 진단용 message 필드가 포함됩니다.
  • 주문 결과: HTTP 200 주문 응답이라도 거부되었을 수 있습니다. status와 reason을 확인하십시오.
  • JSON-RPC 응답: JSON-RPC 엔드포인트는 HTTP 200 응답 안에 숫자형 error.code 값을 유지합니다.

HTTP 오류 응답​

API가 생성하는 모든 HTTP 4xx 및 5xx JSON 오류 응답에는 다음이 포함됩니다.

{
  "error": "existing endpoint value, when present",
  "code": "invalid_field",
  "message": "price must be greater than zero"
}

code는 프로그램 처리를 위한 계약입니다. 이 소문자 식별자를 기준으로 분기하고, 향후 추가될 알 수 없는 값도 안전하게 처리하십시오. message는 진단용 텍스트입니다. 표시하거나 로그에 기록하되 파싱하지 마십시오.

error는 유지되는 레거시 필드입니다. 일부 엔드포인트는 이미 이 필드를 노출하고 있으며 계속 노출하지만, 불투명한 값이며 새로운 계약에 해당하지 않습니다. 준비 상태 세부 정보 및 Retry-After 같은 기존 엔드포인트별 필드는 그대로 유지됩니다.

HEAD 응답에는 본문이 없습니다. HTTP 상태를 평소대로 사용하십시오. Hypercall은 별도의 오류 코드 헤더를 추가하지 않습니다.

출금 사전 검증​

Core 전달 방식의 USDC 출금은 새 출금을 수락하기 전에 수신자 활성화 여부와 전송 호환성을 확인합니다. withdrawal_destination_inactive 및 withdrawal_destination_mode_unsupported는 수신처 오류로 처리하십시오. withdrawal_preflight_unavailable은 검증을 일시적으로 사용할 수 없음을 의미합니다. withdrawal_source_unavailable은 서비스 측에서 호환되는 송금 계정 또는 경로를 복구해야 함을 의미합니다.

이러한 오류는 새로운 출금 차감을 발생시키지 않습니다. 이전에 수락된 요청은 기존 상태를 유지합니다. 사전 검증에 성공했다고 해서 전달이 보장되는 것은 아니므로, 출금의 실행 상태를 계속 모니터링하십시오. EVM 전용 출금에는 HyperCore 계정 적격성이 필요하지 않습니다.

포트폴리오 증거금 계정 모드​

포트폴리오 증거금은 Account를 HyperCore 자산가치(equity)로 평가하며, HyperCore는 unifiedAccount 모드인 Account에 대해서만 이 값을 공개합니다.

  • portfolio로 POST /margin-mode를 호출하면 Account가 다른 모드일 때 400 pm_account_not_unified를 반환합니다. abstraction을 unifiedAccount로 지정한 hl_set_abstraction 디렉티브에 서명하고, HyperCore의 확인을 기다린 뒤 다시 시도하십시오.
  • 현재 HyperCore 자산가치가 없는 포트폴리오 증거금 Account에 대해 GET /portfolio를 호출하면, HyperCore가 해당 Account의 자산가치를 한 번도 공개한 적이 없고 다른 모드로 보고하는 경우 409 pm_account_not_unified를 반환합니다. 그 외의 경우에는 최신 unified 스냅샷이 엔진에 도달할 때까지 503 pm_account_equity_pending을 반환합니다. 보유 중인 자산가치가 오래되었고 HyperCore가 다른 모드를 보고하는 경우, 메시지에 해당 모드가 명시됩니다. pm_account_equity_pending은 잠시 후 다시 시도하고, 메시지에 Account가 unified 모드를 벗어났다고 표시되면 unified 모드를 다시 활성화하십시오.
  • account_abstraction_unavailable (503)은 HyperCore 계정 모드를 읽을 수 없음을 의미합니다. 잠시 후 다시 시도하십시오.

RFQ 레그 수량​

계약 수량은 0.000001 단위로 체결됩니다. POST /rfq/request는 소수점 이하 여섯 자리를 초과하는 레그 수량을 HTTP 400으로 거부하며, 메시지에 내림 처리된 최대 체결 가능 수량이 명시됩니다. 테이커가 정확한 레그 수량에 서명하므로 Hypercall은 수량을 대신 반올림하지 않습니다. 서명 전에 내림 처리한 뒤 다시 제출하십시오.

RFQ 호가 사전 검증 사유​

사전 검증 단계에서 거부된 메이커 호가에는 짧은 사유 코드가 포함됩니다. margin_rejected는 메이커 계정이 해당 패키지에 대한 증거금 검사를 통과하지 못했음을 의미합니다. pricing_unavailable은 예를 들어 내재변동성 표면이나 기준 가격이 없어 거래소가 패키지를 평가할 수 없었음을 의미합니다. 이는 증거금 판단이 아니며, 가격 산정이 복구되면 새 호가는 성공할 수 있습니다.

주문 거부​

주문은 **HTTP 200**과 함께 거부된 실행 결과를 반환할 수 있습니다.

{
  "status": "REJECTED",
  "reason": "Insufficient margin: required=1500.00, equity=1200.00, shortfall=300.00, current_consumed_initial_margin=900.00, incremental_order_initial_margin=600.00, current_consumed_maintenance_margin=500.00, incremental_order_maintenance_margin=250.00"
}

reason은 설명용 텍스트이며 안정적인 코드가 아닙니다. 실시간 값이 포함될 수 있고 검증 로직이 발전함에 따라 바뀔 수 있습니다. 포트폴리오 증거금 부족의 경우 required는 주문 후 전체 개시증거금이며, current_consumed_* 및 incremental_order_* 필드는 기존 사용분과 신규 주문분을 구분합니다. status로 거부된 주문을 식별한 다음 reason을 표시하거나 로그에 기록하십시오. 안정적인 주문 거부 코드 계약은 별도의 프로토콜 및 SDK 작업이 필요합니다.

포트폴리오 증거금 퍼프 주문의 경우, open_orders_initial_margin은 활성 주문 전체에서 독립적으로 선택 가능한 미체결 또는 지정가 전량 체결 상태 중 최악의 상태에서 발생하는 추가 IM입니다. 계정이 IM 미만인 상태에서도 주문을 추가했을 때 해당 범위나 그에 대응하는 최악 체결 시 유지증거금 수용 요건이 증가하지 않는 경우에만 주문이 수락될 수 있습니다. 미체결 주문은 여전히 공개되는 포지션 MM을 변경하지 않습니다. 클라이언트는 주문이 수락되었다고 해서 현재 계정에 자금이 충분하다고 추론해서는 안 되며, 자금이 충분해서 수락된 경우와 리스크를 악화시키지 않아 수락된 경우를 구분하기 위해 진단용 reason을 파싱해서는 안 됩니다.

JSON-RPC 오류​

GET /orderbook은 존재하지 않는 상품에 대해 HTTP 200과 함께 JSON-RPC 형식의 응답을 유지합니다.

{
  "jsonrpc": "2.0",
  "error": {
    "code": 13020,
    "message": "not_found",
    "data": {"object": "instrument_name", "value": "BTC-20200101-1-C"}
  },
  "testnet": false,
  "usDiff": 1,
  "usIn": 1791273938274109,
  "usOut": 1791273938274109
}

숫자형 error.code를 기준으로 분기하십시오. RSM 전용 JSON-RPC 코드는 기본 공개 HTTP 카탈로그에 포함되지 않습니다.

공개 오류 코드 카탈로그​

이 검색 가능한 카탈로그는 공개 OpenAPI 문서의 info.x-hypercall-error-codes 확장에서 생성됩니다. 사용자 대상 HTTP 코드와 항상 활성화된 JSON-RPC 코드만 포함합니다.

Loading API error catalog…

처리 체크리스트​

  • HTTP 클라이언트: code를 기준으로 분기하고, HTTP 상태를 보존하며, Retry-After가 있으면 이를 준수하십시오.
  • 주문 클라이언트: HTTP 요청이 성공했더라도 status: "REJECTED"는 실행 결과로 처리하십시오.
  • JSON-RPC 클라이언트: 엔드포인트의 기본 프로토콜에 맞게 숫자형 error.code를 기준으로 분기하십시오.
  • 모든 클라이언트: 향후 추가될 알 수 없는 코드에 대비한 안전한 기본 처리를 유지하고, 진단 메시지는 절대 파싱하지 마십시오.
최종 업데이트: