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 & Lý do Từ chối

Danh mục đầy đủ các mã lỗi và lý do từ chối.

Định dạng Phản hồi Lỗi​

Phản hồi Lỗi HTTP (Middleware)​

Lỗi JSON có cấu trúc từ middleware (HTTP 4xx/5xx):

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

Từ chối ở Cấp Engine (HTTP 200)​

Các từ chối giao dịch trả về HTTP 200 với OrderUpdateMessage.status = "REJECTED":

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

Quan trọng: Không dựa vào mã trạng thái HTTP để xác định các từ chối giao dịch. Luôn kiểm tra các trường status và reason.

Mã Lỗi Middleware​

Các lỗi này được trả về dưới dạng phản hồi lỗi HTTP với nội dung JSON có cấu trúc.

MãTrạng thái HTTPMô tả
invalid_request400Không thể đọc nội dung request
invalid_json400Phân tích JSON thất bại
missing_field400Thiếu trường bắt buộc
invalid_wallet400Không thể phân tích chuỗi ví
invalid_parameter400Tham số không hợp lệ (ví dụ: size/price phải là chuỗi)
signature_verification_failed400Khôi phục chữ ký EIP-712 thất bại
unsupported_endpoint400Middleware không hỗ trợ đường dẫn này
unauthorized401Signer không được ủy quyền cho ví (xác thực agent thất bại)
internal_error500Kiểm tra ủy quyền agent thất bại bất ngờ

Lý do Từ chối của Engine​

Các lý do này xuất hiện trong OrderUpdateMessage.reason khi status="REJECTED".

Công cụ Đã Đáo hạn​

Lý do: "Instrument has expired"

Nguyên nhân: Lệnh được đặt trên một công cụ đã qua ngày đáo hạn.

Hành động: Kiểm tra ngày đáo hạn của công cụ qua GET /instruments hoặc GET /markets.

Tài khoản Chưa Nạp tiền​

Lý do: "Account has no funds. Please deposit before trading."

Nguyên nhân: Số dư tiền mặt của tài khoản là <= 0.0.

Hành động: Nạp USDC vào ví trước khi giao dịch.

Ký quỹ Không đủ​

Lý do: "Insufficient margin: required={:.2}, available={:.2}, shortfall={:.2}"

Ví dụ: "Insufficient margin: required=1500.00, available=1200.00, shortfall=300.00"

Nguyên nhân: Kiểm tra ký quỹ trước giao dịch phát hiện tài sản thế chấp khả dụng (equity) không đủ để đáp ứng yêu cầu ký quỹ sau khi lệnh được đề xuất.

Đối với tài khoản Standard Margin, tài sản thế chấp yêu cầu phụ thuộc vào phía quyền chọn, loại quyền chọn, giá thực hiện, giá tài sản cơ sở và danh mục hiện tại. Xem Standard Margin để biết mô hình ký quỹ hiện tại khi ra mắt.

Hành động:

  1. Kiểm tra danh mục qua GET /portfolio?wallet=...
  2. Xem lại cách tính ký quỹ trong Margin
  3. Giảm quy mô vị thế hoặc bổ sung tài sản thế chấp

Thiếu Giá Spot​

Lý do: "Failed to get portfolio: No spot price available for underlying: {underlying}"

Nguyên nhân: Engine không thể suy ra giá spot cho tài sản cơ sở cần thiết để mô phỏng khớp lệnh.

Hành động: Kiểm tra kết nối nguồn cấp giá spot của Hyperliquid. Giá spot đến từ nguồn cấp WebSocket allMids.

Hạn chế theo Cấp bậc (Tier)​

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

Nguyên nhân: Ví thuộc tier1 (chỉ được mua/long) và đã cố gắng bán mà không có đủ vị thế mua đã khớp.

Hành động:

  1. Kiểm tra tier qua GET /user-tier?wallet=...
  2. Đảm bảo mọi lệnh bán đều được bảo chứng bởi vị thế mua đã khớp
  3. Liên hệ Hypercall nếu bạn cần quyền writer cho tích hợp nhà tạo lập thị trường

Symbol Không hợp lệ​

Lý do: "Invalid symbol: {symbol}"

Nguyên nhân: Không tồn tại sổ lệnh cho symbol này.

Hành động:

  1. Xác minh thị trường tồn tại qua GET /instrument-specs và GET /markets
  2. Kiểm tra định dạng symbol: UNDERLYING-YYYYMMDD-STRIKE-(C|P)

Lỗi Phân tích Symbol​

Lý do: "Failed to parse symbol: {detail}"

Nguyên nhân: Symbol không khớp với định dạng mong đợi.

Hành động: Xác minh định dạng symbol khớp với UNDERLYING-EXPIRY-STRIKE-(C|P) hoặc kiểu Deribit DDMMMYY.

Lỗi Hủy Lệnh​

Không Tìm thấy Lệnh​

Lý do: "Order not found for cancellation: {client_id}"

Nguyên nhân: Không tìm thấy lệnh với client_id đã cho.

Hành động: Xác minh client_id là chính xác và lệnh tồn tại qua GET /orders?wallet=....

Không Tìm thấy Sổ lệnh​

Lý do: "Orderbook not found for symbol: {symbol}"

Nguyên nhân: Sổ lệnh không tồn tại cho symbol này.

Hành động: Xác minh symbol hợp lệ và thị trường tồn tại.

Lệnh Không có trong Sổ lệnh​

Lý do: "Order {id} not found in orderbook {symbol}"

Nguyên nhân: ID lệnh tồn tại nhưng lệnh không có trong sổ lệnh (có thể đã khớp/đã hủy).

Hành động: Kiểm tra trạng thái lệnh qua GET /orders?wallet=....

Lệnh Đã Khớp​

Lý do: "Order {id} is already filled and cannot be cancelled"

Nguyên nhân: Lệnh đã được khớp toàn bộ trước khi có yêu cầu hủy.

Hành động: Kiểm tra trạng thái lệnh qua GET /orders?wallet=....

Lệnh Đã Bị Hủy​

Lý do: "Order {id} was already cancelled"

Nguyên nhân: Lệnh đã bị hủy trước đó.

Hành động: Kiểm tra trạng thái lệnh qua GET /orders?wallet=....

Xác thực Lệnh Perp​

Lý do: "Perp order missing underlying symbol"

Nguyên nhân: Lệnh perp không bao gồm trường underlying.

Hành động: Đảm bảo lệnh perp bao gồm symbol underlying.

MMP Được Kích hoạt​

Lý do: "MMP triggered during fill processing"

Nguyên nhân: Giới hạn MMP bị vi phạm trong quá trình xử lý khớp lệnh. Lệnh đã được khớp một phần, sau đó MMP kích hoạt và hủy khối lượng còn lại.

Hành động:

  1. Kiểm tra cấu hình MMP qua GET /mmp-config?wallet=...&currency=...
  2. Xem lại các chỉ số cửa sổ khớp lệnh
  3. Điều chỉnh giới hạn MMP hoặc đặt lại trạng thái MMP qua POST /mmp-config/reset

Xem MMP để biết đầy đủ ngữ nghĩa của MMP.

Hủy do MMP (Các Lệnh Khác)​

Lý do: "Order canceled by MMP trigger"

Nguyên nhân: Lệnh bị hủy vì một lệnh khác cho cùng ví+tài sản cơ sở đã kích hoạt MMP.

Hành động: Xem lại cấu hình MMP và hoạt động khớp lệnh.

Lỗi Xác thực ở Cấp Handler​

Các lỗi này trả về HTTP 400 trước khi đến engine.

Xác thực Giá​

Lỗi: "Price validation failed: Price {price} has {n} significant figures, maximum allowed is 5"

Nguyên nhân: Giá vượt quá 5 chữ số có nghĩa.

Hành động: Làm tròn giá về ≤ 5 chữ số có nghĩa.

Định dạng Size/Price​

Lỗi: "Size must be greater than 0" hoặc "Price must be greater than 0"

Nguyên nhân: Size hoặc price là <= 0 hoặc không thể phân tích thành số thực (float).

Hành động: Đảm bảo size và price là các số dương hợp lệ (dưới dạng chuỗi).

Định dạng Symbol Không hợp lệ​

Lỗi: HTTP 400 với thông báo lỗi từ handler

Nguyên nhân: Symbol không thể phân tích thành symbol quyền chọn hợp lệ.

Hành động: Xác minh định dạng symbol: UNDERLYING-YYYYMMDD-STRIKE-(C|P).

Lỗi Lệnh Hàng loạt (Bulk)​

Các endpoint bulk trả về lỗi cho từng mục trong 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"

Mỗi kết quả bao gồm index (vị trí trong mảng request) và boolean success.

Lỗi WebSocket​

Các thông điệp điều khiển WebSocket:

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

Các lỗi phổ biến:

  • "Authentication required for this channel": Đã cố gắng đăng ký kênh riêng tư mà không có ?wallet=
  • "Client not found": Lỗi nội bộ (mất kết nối)

Thực hành Tốt nhất khi Xử lý Lỗi​

  1. Luôn kiểm tra trường status: Không dựa vào mã trạng thái HTTP để xác định các từ chối giao dịch
  2. Phân tích chuỗi reason: Sử dụng chuỗi lý do chính xác để xử lý theo chương trình
  3. Xử lý lỗi bulk: Kiểm tra BulkOrderResult.error cho từng mục trong các request bulk
  4. Logic thử lại: Không thử lại các lệnh REJECTED (hãy khắc phục vấn đề gốc trước)
  5. Ghi log: Ghi log đầy đủ OrderUpdateMessage để gỡ lỗi các từ chối

Bảng Tham chiếu Mã Lỗi​

Lý do Từ chốiDanh mụcTrạng thái HTTPHành động
Instrument has expiredĐáo hạn200Kiểm tra ngày đáo hạn, sử dụng công cụ khác
Account has no funds...Nạp tiền200Nạp tiền (khi đã triển khai)
Insufficient margin: ...Ký quỹ200Giảm quy mô, bổ sung tài sản thế chấp, kiểm tra danh mục
Failed to get portfolio: No spot price...Dữ liệu200Kiểm tra kết nối nguồn cấp Hyperliquid
Tier1 users cannot go short...Tier200Nâng cấp lên tier2 hoặc bảo chứng lệnh bán
Invalid symbol: ...Symbol200Xác minh thị trường tồn tại
Order not found for cancellation: ...Hủy lệnh200Xác minh lệnh tồn tại
Order {id} is already filled...Hủy lệnh200Lệnh đã được thực hiện
Order {id} was already cancelledHủy lệnh200Lệnh đã bị hủy
MMP triggered during fill processingMMP200Xem lại cấu hình MMP, điều chỉnh giới hạn
Order canceled by MMP triggerMMP200Xem lại cấu hình MMP, điều chỉnh giới hạn
signature_verification_failedXác thực400Kiểm tra chữ ký, mã hóa chuỗi
unauthorizedXác thực401Phê duyệt agent hoặc ký bằng ví
Price validation failed: ...Kiểm tra hợp lệ400Làm tròn giá về ≤ 5 chữ số có nghĩa

Gỡ lỗi các Từ chối​

  1. Kiểm tra chi tiết lệnh: Xác minh symbol, price, size, side là chính xác
  2. Kiểm tra danh mục: GET /portfolio?wallet=... để xem vị thế hiện tại và tiền mặt
  3. Kiểm tra tier: GET /user-tier?wallet=... để xác minh các hạn chế theo tier
  4. Kiểm tra MMP: GET /mmp-config?wallet=...&currency=... để xem lại giới hạn MMP
  5. Kiểm tra thị trường: GET /markets và GET /instruments để xác minh công cụ tồn tại
  6. Xem lại log: Log máy chủ có thể chứa ngữ cảnh bổ sung (không được cung cấp qua API)

Tài liệu Tham khảo​

  • Logic từ chối: được thực thi trong trading engine
  • Kiểm tra ký quỹ: được áp dụng trước khi tiếp nhận lệnh
  • Kiểm tra tier: được thực thi theo tier của từng ví
  • Xác thực handler: xác thực request tiêu chuẩn
Cập nhật lần cuối vào