Errors

HTTP Status Codes

Registration Errors

400 — Invalid Nonce

The nonce must be within 60 seconds of the server time.

• Ensure your system clock is synchronized
• Generate a fresh nonce for each registration attempt

400 — Signature Mismatch

The signature does not match the expected message.

• Message format must be exactly: "Register HyperETH: {nonce}"
• Verify you signed with the correct private key
• Ensure the signature is 0x-prefixed hex

400 — Address Mismatch

The address recovered from the signature doesn't match wallet_address.

• Ensure wallet_address matches the address of the signing key

Authentication Errors

401 — Invalid API Key

• API key doesn't exist or has been deactivated
• Ensure you're using the full API key including the api_ prefix
• Ensure the x-api-key header is included in the request

Venue Configuration Errors

400 — Invalid Venue

Venue name not recognized. Supported venues:

hyperliquid, hyena, aster, paradex, grvt, lighter, kuru, nado

400 — Missing Credentials

Required fields are missing for the venue. Required fields per venue:

400 — Wrong Endpoint for Model

Using the wrong setup endpoint for a venue's model:

• Model 1 venues require /setup — not /credentials or /prepare
• Model 2 venues require /prepare + /confirm — not /credentials or /setup
• Model 3 venues require /credentials — not /setup or /prepare

404 — No Credential Found

Attempting to confirm a prepare that hasn't been created, or confirming a different venue than was prepared.

409 — Credential Already Exists

Venue is already configured. Delete the existing credential first:

curl -X DELETE "https://api.hypereth.io/v2/account/venues/{venue}" \
  -H "x-api-key: $API_KEY"

501 — Privy Not Configured

Model 1 venues (Hyperliquid, HyENA) require Privy to be configured on the server. Contact your server administrator.

503 — TEE Not Configured

The TEE sealing service is required for credential encryption. The server administrator must configure the TEE_SEALING_KEY.

Trading Errors

400 — Venue Not Configured

Attempting to trade on a venue that isn't set up. Check configured venues:

curl -s "https://api.hypereth.io/v2/account/venues" \
  -H "x-api-key: $API_KEY" | jq .

503 — DEX Unavailable

The upstream DEX is down or unreachable. Retry after a short delay.

Error Handling Example

import requests
import time

def make_request_with_retry(func, max_retries=3):
    """Retry on transient errors with exponential backoff."""
    for attempt in range(max_retries):
        try:
            resp = func()
            if resp.status_code in [503, 504]:
                if attempt < max_retries - 1:
                    time.sleep(2 ** attempt)
                    continue
            return resp
        except requests.exceptions.RequestException:
            if attempt < max_retries - 1:
                time.sleep(2 ** attempt)
                continue
            raise

# Usage
resp = make_request_with_retry(
    lambda: requests.get(url, headers=headers)
)