> For the complete documentation index, see [llms.txt](https://docs.pearprotocol.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pearprotocol.io/api-integration/error-handling.md).

# 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 |