Errors and Recovery

Errors use a stable code, a readable message, and a request ID. Save the request ID with the operation’s client identifier and timestamp. Keep secrets and signing headers out of logs.

{
  "request_id": "req_example_01",
  "error": {
    "code": "INVALID_ORDER",
    "message": "Quantity must match the exchange size increment.",
    "retryable": false,
    "details": [{
      "field": "quantity",
      "reason": "Use a multiple of 0.001 BTC for this route."
    }]
  }
}

HTTP Codes

Opening the API base URL or a REST route in a browser sends an unsigned request. The response is HTTP 401 with WWW-Authenticate: Trade8-HMAC realm="Trade8 API" and this JSON body:

{
  "request_id": "req_example_01",
  "error": {
    "code": "AUTHENTICATION_REQUIRED",
    "message": "Authentication is required. Send X-Trade8-API-Key, X-Trade8-Timestamp, and X-Trade8-Signature.",
    "retryable": false,
    "details": []
  }
}

X-Request-ID matches the body’s request ID. Follow Authentication and API Keys to prepare signed requests. Keep the API secret in your signing process; send only the key ID, timestamp, and signature.

Status	Meaning	Next Step
200	Successful read or completed configuration change	Process the returned resource
202	Mutation accepted for processing	Follow order, allocation, or transfer state
400	Request syntax or parameter error	Correct the field shown in details
401	Authentication failure	Check signature, timestamp, secret, and key status
403	Account, scope, IP, or eligibility restriction	Review account grants and key policy
404	Resource unavailable under the selected account	Check the ID and account; reconcile timed-out creates by client ID
409	Conflicting request or resource state	Read current state before changing the request
422	Trading, margin, or collateral rule rejected	Correct the order or funding condition
429	Rate limit reached	Honor Retry-After and reduce request pressure
500	Internal processing error	Reconcile mutations before retrying
503	Service or exchange temporarily unavailable	Honor Retry-After; reconcile affected resources

Codes Your Client Should Handle

Error Code	Status	Recovery
AUTHENTICATION_REQUIRED	401	Supply the three authentication headers; review account access if the response persists
INVALID_SIGNATURE	401	Compare the exact signed path, query, body, and idempotency key
TIMESTAMP_EXPIRED	401	Synchronize the clock and sign again
KEY_EXPIRED	401	Load an active key and reconnect private streams
SCOPE_DENIED	403	Grant the endpoint’s required scope through the account access process
ACCOUNT_DENIED	403	Select an account authorized for this key
IP_NOT_ALLOWED	403	Verify the server’s outbound IP against the key allowlist
RESOURCE_NOT_FOUND	404	Verify the identifier and account
IDEMPOTENCY_CONFLICT	409	Recover the original request; use a new key for a new operation
REQUEST_IN_PROGRESS	409	Wait and read the existing resource before retrying
CLIENT_ORDER_ID_CONFLICT	409	Look up the existing order by client order ID
REVISION_CONFLICT	409	Read the latest order revision before amending
MARGIN_MODE_CONFLICT	409	Review open orders, positions, and exchange margin rules
CURSOR_EXPIRED	400	Restart the query with an overlapping time range
INVALID_ORDER	422	Correct type, units, precision, or required fields
INSUFFICIENT_MARGIN	422	Reduce size or arrange eligible collateral
POST_ONLY_WOULD_TAKE	422	Move the quote to a passive price or change the order policy
ORDER_NOT_AMENDABLE	422	Read the terminal or conditional order state
NO_ELIGIBLE_VENUE	422	Review settlement asset, exchange filters, capability, and collateral
ALLOCATION_NOT_ELIGIBLE	422	Select a destination from the custody account’s eligible exchanges
RATE_LIMITED	429	Wait for the indicated reset and use backoff
VENUE_UNAVAILABLE	503	Pause dependent trading and monitor exchange status

A failed validation is returned before acceptance. Exchange rejections that arrive later are reflected in child and parent order state. Read fills even when a routed order finishes with an unfilled remainder.

Retry Decisions

retryable describes whether a retry may help after recovery steps. A lost response or server error can leave an operation accepted. Query the resource first, then retry the same request identity where needed. Idempotency and Timeout Recovery gives the full sequence.

A batch can contain accepted and rejected items in the same HTTP 202 response. Check each item’s accepted flag and its order or error. Correct rejected items individually while continuing to track accepted orders.

Report an Issue

Contact Us with the request ID, UTC time, method and path, account ID, client order ID, and observed error. Include exchange IDs such as binance or hyperliquid where relevant. Redact credentials, signatures, and personal identity documents.