Errors and idempotency

HTTP responses

{
  "error": {
    "type": "api_error",
    "code": "exchange_capacity_busy",
    "message": "Exchange request capacity is busy; retry with the same idempotency key"
  }
}

Request-Id identifies the HTTP request. Authenticated API responses are not cacheable.

Request limits

Each API key allows 120 requests per minute. The public endpoint also applies an abuse-protection ceiling of approximately 5,000 requests per source IP over five minutes; clients sharing an IP share that ceiling. Exchange capacity and Hyperliquid account limits apply separately. A 429 response includes Retry-After; edge rejections may omit Request-Id.

API key checks and key registration or revocation also have a small per-server capacity for requests whose caller is not yet known. When this capacity is full, the API returns 429 with code unauthenticated_capacity_busy and Retry-After: 1.

Idempotency

Send an Idempotency-Key header containing 8–128 printable ASCII characters on every trading mutation. Choose one key per logical action. The key is scoped to the API credential. Reusing it with the same parameters returns the recorded result; changing parameters returns 409.

A timeout is not proof that a trade failed. Retry the same action with the same idempotency key. Never submit a replacement under a new key simply because the original response was lost. Switching API credentials also changes the idempotency namespace.

For orders, retrieve the returned order UUID to reconcile an unknown result against Hyperliquid. An unknown exchange order ID is not proof of nonexecution. An unresolved mutation of the same order blocks another mutation of that order. Unrelated orders and commands may proceed with their own idempotency keys.

For leverage, margin, and TWAP actions, retrieve the operation UUID. An unknown operation remains unknown unless its execution result is known; a retrieval does not replay the action. Inspect the account’s exchange state before deciding on a separate action. There is no automatic retry of signed exchange writes.

A confirmed single-attempt HTTP 429 or local pre-dispatch rejection permits retry with the same idempotency key after the indicated delay. Transport timeouts and lost responses do not get this treatment.

Order statuses

open, waiting_for_trigger, filled, canceled, rejected, and unknown describe the order resource. Unknown fill amounts or average prices are null, not zero. A rejected modification can also cancel the original order at Hyperliquid. Legend reconciles the original order and sets its error field; if reconciliation is unavailable, its status is unknown. Read fills for execution details; order status alone does not provide a complete fill history.