# Hyperliquid API Errors and Fixes

> Each Hyperliquid API error message with its cause and fix: tick size, minimum order value, insufficient margin, API wallet does not exist, open interest cap and more.

- Canonical URL: https://hiperwire.io/build/hyperliquid-api-errors
- Last verified: November 17, 2026
- Publisher: HIPERWIRE (https://hiperwire.io). Not affiliated with Hyperliquid.

This page lists the error messages that the Hyperliquid API returns, with the cause and the fix for each one. Search this page for the exact text of your error.

## How Hyperliquid reports errors

Hyperliquid reports most errors with HTTP status 200. The Python SDK does not raise an exception for them. There are three levels.

**Level 1: the HTTP request fails.** The request is malformed or rate limited. The SDK raises `ClientError` (status 4xx) or `ServerError` (status 5xx).

**Level 2: the whole action is rejected.** The response is HTTP 200 with `status` set to `err`:

```json
{"status": "err", "response": "User or API Wallet 0x... does not exist."}
```

**Level 3: one order in the action is rejected.** The response is HTTP 200 with `status` set to `ok`, and the entry for that order has an `error`:

```json
{"status": "ok", "response": {"type": "order", "data": {"statuses": [
  {"error": "Order must have minimum value of $10."}
]}}}
```

`statuses` has one entry for each order in the request, in the same order. Check both levels each time:

```python
result = exchange.order("ETH", True, size, price, {"limit": {"tif": "Gtc"}})

if result["status"] != "ok":
    raise RuntimeError(result["response"])                 # level 2

for status in result["response"]["data"]["statuses"]:
    if "error" in status:
        raise RuntimeError(status["error"])                # level 3
```

Some errors depend only on the request, for example an empty batch. Hyperliquid then returns one error for the whole batch, and the same error can appear one time for each order.

## Signing and account errors

| Message | Cause | Fix |
| --- | --- | --- |
| `User or API Wallet 0x... does not exist.` | The address that Hyperliquid recovered from the signature is not a known account or an approved API wallet on this network. | Check that the key is the API wallet key, that the wallet is approved for this account, and that you use the correct network. An account that has never deposited also gives this error. |
| `Failed to deserialize the JSON body into the target type` (HTTP 422) | The request body has a wrong field name, a wrong type or a missing field. | Compare the body with the docs. Prices and sizes are strings in the raw API. |
| `KeyError: 'xyz:NVDA'` (Python SDK) | The SDK does not know the market name. | For a HIP-3 market, create the client with `perp_dexs`. See [HIP-3 markets through the API](https://hiperwire.io/build/hyperliquid-hip3-api). |

If the address in the `does not exist` message is different on each request, the signature does not match the payload. This occurs when you sign by hand and the signed fields differ from the sent fields, for example a price with trailing zeros. Use the SDK to sign.

## Price and size errors

| Message | Cause | Fix |
| --- | --- | --- |
| `Price must be divisible by tick size.` | The price has more than 5 significant figures, or more than `6 - szDecimals` decimal places (8 for spot). | Round the price. See the code below. |
| `Order must have minimum value of $10.` | Size times price is less than $10. | Increase the size. Size is in asset units, not USD. |
| `Order must have minimum value of 10 {quote_token}.` | A spot order is below the minimum value. | Increase the size. |
| `Order price too far from oracle` | The limit price is too far from the oracle price. | Use a price nearer to the market. |
| `Invalid TP/SL price.` | The trigger price of a take-profit or stop-loss order is on the wrong side of the market. | A stop-loss for a long must be below the market. A take-profit for a long must be above it. |

```python
def round_price(px: float, sz_decimals: int, is_spot: bool = False) -> float:
    return round(float(f"{px:.5g}"), (8 if is_spot else 6) - sz_decimals)
```

`szDecimals` for each asset is in the `meta` response. Integer prices are always valid.

## Margin and position errors

| Message | Cause | Fix |
| --- | --- | --- |
| `Insufficient margin to place order.` | The account does not have enough free margin. | Reduce the size, increase the leverage setting, or add collateral. For a HIP-3 market in standard account mode, the collateral must be on that dex. |
| `Reduce only order would increase position.` | A reduce-only order is on the same side as the position, or there is no position. | Check the position side and size before you send the order. |
| `Order would cause position to exceed margin tier limit at current leverage` | The position would be larger than the margin tier allows at this leverage. | Reduce the leverage or the size. |
| `(Spot-only) Order has insufficient spot balance to trade` | The spot balance does not cover the order. | Check the spot balance and the open orders that hold it. |

## Matching errors

| Message | Cause | Fix |
| --- | --- | --- |
| `Post only order would have immediately matched, bbo was {bbo}.` | An `Alo` order has a price that crosses the book. | Use a less aggressive price. The message contains the best bid and offer. |
| `Order could not immediately match against any resting orders.` | An `Ioc` order found no order to match at its price. | Use a more aggressive price, or increase the slippage of a market order. |
| `No liquidity available for market order.` | The book has no orders on the other side. | Wait, or use a limit order. |

## Open interest cap errors

These occur mostly on new and HIP-3 markets, which have a limit on total open interest.

| Message | Cause | Fix |
| --- | --- | --- |
| `Order would increase open interest while open interest is capped` | The market is at its open interest cap. An order that opens or flips a position is rejected. | Orders that reduce a position still work. Wait for the cap to clear. |
| `Order rejected due to price more aggressive than oracle while at open interest cap` | At the cap, the order price is more aggressive than the oracle price. | Use a price at or behind the oracle price. |
| `Order would increase open interest too quickly` | Open interest increased faster than the market allows. | Send a smaller order, or wait. |

## Cancel errors

| Message | Cause | Fix |
| --- | --- | --- |
| `Order was never placed, already canceled, or filled.` | The order id is not an open order. | This is normal when a fill and a cancel cross. Read `orderStatus` or your fills to find what occurred. Do not send the cancel again. |

## Rate limit errors

An HTTP 429 response means that your IP address used more than 1200 weight in one minute. A rate-limited account address can send 1 action each 10 seconds. See [Hyperliquid API rate limits](https://hiperwire.io/build/hyperliquid-api-rate-limits).

## Problems that return no error

- **Positions and orders are empty.** The code reads the API wallet address. Read the main account address. See [Hyperliquid API wallets](https://hiperwire.io/build/hyperliquid-api-wallets).
- **A HIP-3 market is missing from prices or positions.** The request has no `dex` field.
- **The order is ten times too large or too small.** The size is in asset units, not USD and not contracts.
- **The code reports success for a rejected order.** The code catches exceptions but does not check `status` and `statuses`.

## Sources

- [Error responses](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/error-responses), Hyperliquid docs. The message strings in the tables come from this page.
- [Tick and lot size](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/tick-and-lot-size), Hyperliquid docs
- The `does not exist` response and the HTTP 422 response were reproduced against the testnet and mainnet APIs on November 17, 2026.
