Errors - Hyperprop Platform API

Response envelope

Success responses always wrap the payload:

{ "success": true, "data": { ... }, "message": "optional human-readable note" }

Errors — including request-validation failures, auth failures, and errors proxied from the trade engine — always return this single uniform shape:

{
  "success": false,
  "statusCode": 404,
  "error": "Not Found",
  "message": "No Hyperprop user found with that email. The trader must have a Hyperprop account before an account can be created for them.",
  "code": "TRADER_NOT_FOUND"
}

Parse rule of thumb: check success; on false, switch on code — never on message text, which can be reworded at any time. Some errors carry additional structured context alongside these fields (for example, payout rejections include a consistency block).

Common codes

Code	Meaning
`VALIDATION_ERROR`	Malformed payload, params, or query
`UNAUTHORIZED`	Missing or invalid credentials
`INSUFFICIENT_PERMISSIONS` / `NOT_ADMIN`	Key lacks `write` / `admin`
`*_NOT_FOUND`	The referenced resource does not exist
`*_NOT_IN_ORG`	Resource belongs to another organization
`IDEMPOTENCY_KEY_IN_PROGRESS`	Duplicate request still in flight — back off and retry
`ENGINE_UNREACHABLE`	Trade engine down — retry with the same idempotency key
`RATE_LIMITED`	Trade API only (429) — sleep `rate_limit.retry_after` seconds and retry; see Rate Limits

Endpoint-specific codes (for example payout OPEN_EXPOSURE, CONSISTENCY_BLOCKED) are documented on each endpoint in the API Reference.

Retry guidance

ENGINE_UNREACHABLE and any 5xx: retry with the same idempotency key — 5xx responses are never cached, so the retry re-executes safely.
IDEMPOTENCY_KEY_IN_PROGRESS (409): your own duplicate is still running; back off briefly and retry to receive the cached response.
4xx validation errors: fix the payload and use a fresh idempotency key.

Related topics

Get integration health (alerts, errors, insights)Revoke one of the trader's API keys Set or clear a trading account's display nickname.Delete all copy trading configs List the trader's API keys

⌘I