# Error Handling

### Error Handling

All API errors follow a consistent JSON format:

```json
{
  "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 |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.pearprotocol.io/api-integration/error-handling.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.