Error Handling

Error Handling

All API errors follow a consistent JSON format:

{
  "statusCode": 400,
  "code": "HL_INSUFFICIENT_MARGIN",
  "message": "Not enough margin to place order"
}

Field	Description
statusCode	HTTP status code
code	Machine-readable error code (see table below)
message	Human-readable error description

Some errors include an additional context field with extra details.

Error Codes

Position

Code	Description
POSITION_NOT_FOUND	Position does not exist
POSITION_NOT_OPEN	Position is not in OPEN status
POSITION_UNAUTHORIZED	User does not own this position

Order

Code	Description
ORDER_NOT_FOUND	Order does not exist
INVALID_ORDER_STATUS	Order is not in the expected status
INVALID_ORDER_TYPE	Unsupported order type

Execution

Code	Description
ACTIVE_TRADE_TIMEOUT	Another trade is still processing for this address
UNSUPPORTED_EXECUTION_TYPE	Invalid execution type
DUPLICATE_TRIGGER	A trigger order with the same parameters already exists
HL_CANCEL_FAILED	Failed to cancel order on Hyperliquid

Hyperliquid

Code	Description
HL_INSUFFICIENT_MARGIN	Not enough margin to place order
HL_AGENT_WALLET_REVOKED	Agent wallet access has been revoked
HL_TICK_SIZE	Price does not conform to tick size
HL_MIN_TRADE_VALUE	Trade value below minimum
HL_REDUCE_ONLY	Reduce-only order would increase position
HL_POST_ONLY_WOULD_MATCH	Post-only order would match immediately
HL_IOC_NO_MATCH	IOC order found no match
HL_BAD_TRIGGER_PRICE	Invalid trigger price
HL_NO_LIQUIDITY	Insufficient liquidity
HL_OPEN_INTEREST_CAP	Open interest cap reached
HL_OPEN_INTEREST_RATE	Open interest rate limit hit
HL_INSUFFICIENT_SPOT_BALANCE	Not enough spot balance
HL_PRICE_TOO_FAR_FROM_ORACLE	Order price too far from oracle price
HL_MAX_POSITION_EXCEEDED	Maximum position size exceeded
HL_ORDER_MISSING	Order not found on Hyperliquid
HL_ORDER_FAILED	Order execution failed on Hyperliquid

Validation

Code	Description
INVALID_ADDRESS	Malformed wallet address
MISSING_REQUIRED_FIELD	Required field not provided
INVALID_FIELD_VALUE	Field value out of range or wrong type
UNSUPPORTED_TRIGGER_TYPE	Trigger type not supported for this operation
INVALID_POSITION_STRUCTURE	Invalid long/short asset configuration

Ladder

Code	Description
INVALID_LADDER_CONFIG	Invalid ladder order configuration
LADDER_CREATION_FAILED	Failed to create ladder order

TWAP

Code	Description
TWAP_DURATION_REQUIRED	TWAP duration not specified
TWAP_INSUFFICIENT_VALUE	Order value too small for TWAP
TWAP_CHUNK_SCHEDULING_FAILED	Failed to schedule TWAP chunks

Leverage

Code	Description
LEVERAGE_CONFIG_FAILED	Failed to configure leverage on Hyperliquid

Risk Parameters

Code	Description
INVALID_RISK_PARAMETERS	Invalid TP/SL configuration

Vault

Code	Description
VAULT_WALLET_NOT_FOUND	Vault wallet does not exist
VAULT_UNAUTHORIZED	User not authorized for this vault
VAULT_UNSUPPORTED_TOKEN	Token not supported for vault operations
VAULT_MISSING_CONFIG	Vault configuration incomplete
VAULT_INITIALIZATION_FAILED	Failed to initialize vault
VAULT_CREATION_FAILED	Failed to create vault

Generic

Code	Description
INTERNAL_ERROR	Unexpected server error