Limits, errors, and production recovery

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:

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.