> For the complete documentation index, see [llms.txt](https://docs.hello.trade/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hello.trade/developer-tools/error-codes.md).

# Error Codes

## Error Response Format

### WebSocket

```json
{
  "type": "error",
  "code": 4001,
  "message": "Signature verification failed"
}
```

### REST API

```json
{
  "error": "Signature verification failed"
}
```

REST API errors return standard HTTP status codes (400, 403, 404, 500, 503) with error message in response body.

***

## Error Codes

### Authentication Errors (4000-4019)

| Code | Error              | Description                                                                                   |
| ---- | ------------------ | --------------------------------------------------------------------------------------------- |
| 4000 | INVALID\_REQUEST   | Malformed request or missing required fields                                                  |
| 4001 | INVALID\_SIGNATURE | Signature verification failed                                                                 |
| 4002 | INVALID\_NONCE     | Nonce validation failed (expired, replay, or out of window)                                   |
| 4003 | NOT\_AUTHENTICATED | Connection not authenticated                                                                  |
| 4004 | WALLET\_MISMATCH   | Signed wallet doesn't match authenticated wallet                                              |
| 4015 | USER\_NOT\_INVITED | Wallet has not been granted app access. Apply a referral code via `POST /api/referral/apply`. |

### Validation Errors (4020-4049)

| Code | Error                            | Description                                                                                            |
| ---- | -------------------------------- | ------------------------------------------------------------------------------------------------------ |
| 4029 | RATE\_LIMIT\_EXCEEDED            | Request rate limit exceeded (20 req/s per authenticated wallet)                                        |
| 4030 | INVALID\_ORDER\_TYPE             | Invalid order type                                                                                     |
| 4031 | INVALID\_TIME\_IN\_FORCE         | Invalid time in force value                                                                            |
| 4032 | INVALID\_ORDER\_PRICE            | Invalid or missing price for order type                                                                |
| 4033 | ALREADY\_SUBSCRIBED              | Connection already subscribed to trading stream                                                        |
| 4034 | INVALID\_ORDER\_QUANTITY         | Invalid order quantity                                                                                 |
| 4035 | SUSTAINED\_RATE\_LIMIT\_EXCEEDED | Signed request budget exhausted (see [Nonce & Rate Limits](/developer-tools/nonce-and-rate-limits.md)) |
| 4040 | ACCOUNT\_NOT\_FOUND              | Trading account not found                                                                              |
| 4041 | ORDER\_NOT\_FOUND                | Cancel/replace target already filled, cancelled, or expired — benign race, safe to ignore              |

### Business Logic Errors (4100-4199)

| Code | Error                   | Description                            |
| ---- | ----------------------- | -------------------------------------- |
| 4100 | INSUFFICIENT\_MARGIN    | Insufficient margin for operation      |
| 4101 | ORDER\_TOO\_SMALL       | Order notional size below minimum ($5) |
| 4102 | MAX\_LEVERAGE\_EXCEEDED | Leverage exceeds instrument maximum    |
| 4103 | OI\_CAP\_EXCEEDED       | Order would exceed open interest cap   |

### Server Errors (5000-5099)

| Code | Error                    | Description                          |
| ---- | ------------------------ | ------------------------------------ |
| 5000 | INTERNAL\_ERROR          | Internal server error                |
| 5001 | EXCHANGE\_ERROR          | Exchange matching engine error       |
| 5002 | LEDGER\_UNAVAILABLE      | Risk engine unavailable              |
| 5003 | EXCHANGE\_ACCOUNT\_ERROR | Account creation or retrieval failed |

***

***

## HTTP Status Codes

| Status | Description           | Typical Cause                                                                                                    |
| ------ | --------------------- | ---------------------------------------------------------------------------------------------------------------- |
| 200    | Success               | Request completed successfully                                                                                   |
| 400    | Bad Request           | Invalid parameters or signature validation failed                                                                |
| 403    | Forbidden             | Wallet not invited. Body starts with `USER_NOT_INVITED:` — apply a referral code via `POST /api/referral/apply`. |
| 404    | Not Found             | Resource does not exist                                                                                          |
| 500    | Internal Server Error | Server-side error                                                                                                |
| 503    | Service Unavailable   | Transient — auth-service unreachable, safe to retry                                                              |

***

## Error Handling

### Retryable Errors

| Code | Retry Strategy                                 |
| ---- | ---------------------------------------------- |
| 5000 | Retry with exponential backoff                 |
| 5002 | Retry after delay (service may be unavailable) |
| 503  | Retry after delay                              |

### Non-Retryable Errors

| Code | Required Action                         |
| ---- | --------------------------------------- |
| 4001 | Fix signature generation                |
| 4002 | Generate fresh nonce                    |
| 4041 | None — order already gone; do not retry |
| 4100 | Deposit margin or reduce position size  |
| 4101 | Increase order quantity                 |
| 4102 | Reduce leverage or position size        |
| 4103 | Reduce order size                       |

### Rate Limit Handling

When receiving error code 4029:

* Stop sending requests immediately
* Wait for rate limit window to reset (1 second)
* Implement exponential backoff for subsequent requests

When receiving error code 4035 (sustained budget exhausted):

* Reduce your sustained request rate — the budget frees as older signed requests age past the 5-minute nonce window
* Cancels are granted 2x budget headroom and keep working, so always prefer cancelling resting orders over waiting