> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperprop.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> One uniform envelope, machine-readable codes.

## Response envelope

**Success** responses always wrap the payload:

```json theme={null}
{ "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:

```json theme={null}
{
  "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"
}
```

<Note>
  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).
</Note>

## 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](/concepts/rate-limits) |

Endpoint-specific codes (for example payout `OPEN_EXPOSURE`,
`CONSISTENCY_BLOCKED`) are documented on each endpoint in the
[API Reference](/api-reference).

## Retry guidance

* `ENGINE_UNREACHABLE` and any 5xx: retry with the same
  [idempotency key](/concepts/idempotency) — 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)](/platform-api/organization/get-integration-health-alerts-errors-insights.md)
- [Revoke one of the trader's API keys](/trade-api/account/revoke-one-of-the-traders-api-keys.md)
- [Set or clear a trading account's display nickname.](/trade-api/account/set-or-clear-a-trading-accounts-display-nickname.md)
- [Delete all copy trading configs](/trade-api/copy-trading/delete-all-copy-trading-configs.md)
- [List the trader's API keys](/trade-api/account/list-the-traders-api-keys.md)