> Use the canonical URL for citations. For the complete Predict API documentation index, fetch https://docs.staging.trypredict.com/llms.txt.

# Limits, errors, and production recovery

> Handle Hyperliquid rate limits, bounded history, order errors, reconnects, idempotency, and operational differences from REST-first prediction exchanges.

Production clients must treat transport delivery, action acceptance, fills, and balance settlement as separate states.

## Rate limits

Hyperliquid applies an aggregate IP weight limit of 1,200 per minute. Common weight rules include:

| Request                                                                        | Weight                                         |
| ------------------------------------------------------------------------------ | ---------------------------------------------- |
| Documented `/exchange` action                                                  | `1 + floor(batch length / 40)`                 |
| `l2Book`, `allMids`, `orderStatus`, `spotClearinghouseState`, `exchangeStatus` | 2                                              |
| `userRole`                                                                     | 60                                             |
| Other documented `/info` requests                                              | 20 plus response-size weights where applicable |

WebSocket limits include 10 connections, 30 new connections per minute, 1,000 subscriptions, 10 unique users across account subscriptions, 2,000 sent messages per minute, and 100 in-flight post requests.

Address action limits are separate and scale with cumulative traded notional. Every address begins with a request buffer, while cancels receive extra capacity so risk can still be reduced.

### Writing through Predict

The IP weight above is counted against the source address a request leaves from, and a write sent to `/v1/trading/*` leaves from one of Predict's, not yours. Predict spreads that traffic over a pool of addresses it owns and routes each wallet to a fixed one, so your throughput does not depend on who else shares your NAT.

Two limits then apply on top of Hyperliquid's, and both answer `429` with `Retry-After`:

* While an address is busy, no single caller may hold more than an equal share of it. Alone on one, you can spend the whole 1,200.
* When Hyperliquid rate limits an address, Predict adopts that answer for as long as Hyperliquid asks rather than forwarding into a limit that is already refusing.

Address-based limits are unaffected: those follow the wallet that signed, wherever the request came from.

## Error model

Validate four layers:

1. Network and HTTP status.
2. Top-level exchange `status`.
3. `response.type` matches the submitted action.
4. Every entry in `response.data.statuses` is success, resting, or filled rather than `error`.

Common failures include invalid tick precision, notional below 10 quote tokens, insufficient spot balance, post-only crossing, IOC with no match, and an order that was already filled or canceled.

## Data retention and recovery

Time-range reads return at most 500 records or distinct blocks. `userFills` and `historicalOrders` return at most 2,000 records, `userFillsByTime` exposes only the most recent 10,000 fills, and candles retain at most 5,000 intervals.

Persist local intent and execution history if your application needs a complete audit trail. A REST-shaped compatibility service must own idempotency, durable archives, normalized position views, and any sequenced book-delta contract it exposes.

## Trading-client checklist

* Keep staging/testnet and production/mainnet identifiers isolated.
* Generate and persist a client order ID before signing.
* Keep a unique nonce counter per signing key.
* Use WebSockets for low-latency updates and HTTP snapshots for recovery.
* Arm and refresh a dead-man switch for unattended strategies.
* Reconcile orders, fills, balances, and ledger updates after reconnects or timeouts.
* Store signing keys outside frontend code and documentation tooling.