Trang này được dịch tự động. Bản gốc tiếng Anh là phiên bản chính thức. Đọc bằng tiếng Anh →
Chuyển đến nội dung chính

Lỗi API

Hãy sử dụng bề mặt phản hồi tương ứng với yêu cầu:

  • Lỗi HTTP: phản hồi JSON 4xx hoặc 5xx có trường code ổn định và trường message mang tính chẩn đoán.
  • Kết quả lệnh: phản hồi lệnh HTTP 200 vẫn có thể bị từ chối. Hãy kiểm tra status và reason của phản hồi.
  • Phản hồi JSON-RPC: các endpoint JSON-RPC giữ giá trị số error.code bên trong phản hồi HTTP 200.

Phản hồi lỗi HTTP​

Mọi phản hồi lỗi JSON HTTP 4xx và 5xx do API tạo ra đều bao gồm:

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

code là hợp đồng dành cho xử lý bằng chương trình. Hãy rẽ nhánh theo định danh chữ thường này và xử lý an toàn các giá trị chưa biết trong tương lai. message là văn bản chẩn đoán. Bạn có thể hiển thị hoặc ghi log, nhưng không nên phân tích cú pháp nó.

error là trường cũ được giữ lại. Một số endpoint đã cung cấp trường này và sẽ tiếp tục như vậy, nhưng nội dung của nó không minh bạch và không phải là hợp đồng mới. Các trường riêng của từng endpoint, chẳng hạn chi tiết readiness và Retry-After, vẫn được giữ nguyên.

Phản hồi HEAD không có body. Hãy sử dụng mã trạng thái HTTP như bình thường; Hypercall không thêm header mã lỗi riêng.

Kiểm tra trước khi rút tiền​

Các lệnh rút USDC giao qua Core sẽ kiểm tra trạng thái kích hoạt của người nhận và khả năng tương thích chuyển khoản trước khi chấp nhận một lệnh rút mới. Hãy xử lý withdrawal_destination_inactive và withdrawal_destination_mode_unsupported như lỗi về địa chỉ đích. withdrawal_preflight_unavailable nghĩa là việc xác minh tạm thời không khả dụng. withdrawal_source_unavailable yêu cầu dịch vụ khôi phục một tài khoản gửi hoặc tuyến chuyển tương thích.

Các lỗi này không tạo ra khoản ghi nợ rút tiền mới. Yêu cầu đã được chấp nhận trước đó vẫn giữ nguyên trạng thái hiện tại. Việc kiểm tra trước thành công không đảm bảo tiền sẽ được chuyển đến; hãy tiếp tục theo dõi trạng thái thực thi của lệnh rút. Các lệnh rút chỉ trên EVM không yêu cầu tài khoản HyperCore đủ điều kiện.

Chế độ tài khoản Portfolio Margin​

Portfolio margin định giá Account dựa trên vốn chủ sở hữu HyperCore của tài khoản, và HyperCore chỉ công bố giá trị này cho các Account ở chế độ unifiedAccount.

  • POST /margin-mode với portfolio trả về 400 pm_account_not_unified khi Account đang ở chế độ khác. Hãy ký directive hl_set_abstraction với abstraction unifiedAccount, chờ HyperCore xác nhận, sau đó thử lại.
  • GET /portfolio cho một Account portfolio margin chưa có vốn chủ sở hữu HyperCore hiện tại sẽ trả về 409 pm_account_not_unified khi HyperCore chưa từng công bố vốn chủ sở hữu cho Account đó và báo cáo tài khoản đang ở chế độ khác. Nếu không, endpoint trả về 503 pm_account_equity_pending cho đến khi một snapshot unified hiện tại đến được engine; khi vốn chủ sở hữu được lưu giữ đã cũ và HyperCore báo cáo chế độ khác, thông báo sẽ nêu tên chế độ đó. Hãy thử lại pm_account_equity_pending sau ít phút, và bật lại chế độ unified nếu thông báo cho biết Account đã rời khỏi chế độ này.
  • account_abstraction_unavailable (503) nghĩa là không thể đọc chế độ tài khoản HyperCore. Hãy thử lại sau ít phút.

Quy mô leg trong RFQ​

Quy mô hợp đồng được thực thi theo đơn vị 0.000001. POST /rfq/request từ chối quy mô leg có hơn sáu chữ số thập phân với HTTP 400; thông báo sẽ nêu quy mô lớn nhất có thể thực thi, đã làm tròn xuống. Hypercall không tự làm tròn quy mô thay bạn, vì taker ký chính xác quy mô từng leg. Hãy làm tròn xuống trước khi ký và gửi lại.

Lý do từ chối báo giá RFQ khi kiểm tra trước​

Báo giá của maker bị từ chối trong bước kiểm tra trước sẽ kèm một mã lý do ngắn. margin_rejected nghĩa là tài khoản của maker không vượt qua kiểm tra ký quỹ cho gói lệnh. pricing_unavailable nghĩa là sàn không thể định giá gói lệnh, chẳng hạn vì thiếu bề mặt biến động ngụ ý hoặc giá tham chiếu; đây không phải quyết định về ký quỹ, và một báo giá mới có thể thành công khi việc định giá được khôi phục.

Từ chối lệnh​

Một lệnh có thể trả về HTTP 200 kèm kết quả thực thi bị từ chối:

{
  "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 là văn bản giải thích, không phải mã ổn định. Trường này có thể chứa giá trị thời gian thực và thay đổi khi logic xác thực phát triển. Với trường hợp không đủ portfolio margin, required là tổng ký quỹ ban đầu sau khi đặt lệnh, còn các trường current_consumed_* và incremental_order_* tách mức sử dụng hiện có khỏi lệnh mới. Hãy dùng status để xác định lệnh bị từ chối, sau đó hiển thị hoặc ghi log reason. Một hợp đồng mã từ chối lệnh ổn định sẽ là phần việc riêng về giao thức và SDK.

Với lệnh perp ở chế độ Portfolio margin, open_orders_initial_margin là IM bổ sung từ trạng thái xấu nhất có thể chọn độc lập, gồm chưa khớp hoặc khớp toàn bộ tại giá giới hạn, trên các lệnh đang hoạt động. Một lệnh có thể được chấp nhận khi tài khoản đang dưới IM chỉ khi việc thêm lệnh đó không làm tăng phạm vi này hoặc yêu cầu năng lực ký quỹ duy trì tương ứng trong trường hợp khớp xấu nhất. Lệnh đang mở vẫn không làm thay đổi MM vị thế đã công bố. Client không được suy luận rằng việc chấp nhận lệnh nghĩa là tài khoản hiện tại đã được nạp đủ vốn, và không được phân tích reason chẩn đoán để phân biệt giữa chấp nhận do đủ vốn và chấp nhận do không làm xấu thêm trạng thái.

Lỗi JSON-RPC​

GET /orderbook giữ phản hồi kiểu JSON-RPC cho trường hợp không tìm thấy công cụ, với HTTP 200:

{
  "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
}

Hãy rẽ nhánh theo giá trị số error.code. Các mã JSON-RPC riêng của RSM không thuộc danh mục HTTP công khai mặc định.

Danh mục mã lỗi công khai​

Danh mục có thể tìm kiếm này được tạo từ phần mở rộng info.x-hypercall-error-codes trong tài liệu OpenAPI công khai. Danh mục chỉ chứa các mã HTTP dành cho người dùng và các mã JSON-RPC luôn bật.

Loading API error catalog…

Danh sách kiểm tra khi xử lý​

  • Client HTTP: rẽ nhánh theo code, giữ nguyên mã trạng thái HTTP và tuân thủ Retry-After khi có.
  • Client đặt lệnh: coi status: "REJECTED" là kết quả thực thi, dù yêu cầu HTTP đã thành công.
  • Client JSON-RPC: rẽ nhánh theo giá trị số error.code cho giao thức gốc của endpoint.
  • Mọi client: luôn có phương án dự phòng an toàn cho các mã chưa biết trong tương lai và không bao giờ phân tích cú pháp thông báo chẩn đoán.
Cập nhật lần cuối vào