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

# Error Responses

Errors are returned either for the entire request or for an individual item in a batched exchange
action. Clients must handle both forms.

## Request Errors

A rejected request normally returns a non-`200` HTTP status and a machine-readable `code`:

```json theme={null}
{
  "error": "Missing 'action.type' field",
  "code": "MISSING_FIELD",
  "field": "action.type",
  "timestamp": 1785254400000
}
```

`field`, `intentId`, and `retryAfter` are included only when relevant. Some read endpoints return the
older `{ "error": "..." }` shape without a code. Error messages can change; use `code` for program
logic when it is present.

### Error Codes

| Error source  | Error code             | Meaning                                                   |
| ------------- | ---------------------- | --------------------------------------------------------- |
| Request       | `UNKNOWN_TYPE`         | The action or request type is not supported               |
| Request       | `MISSING_FIELD`        | A required field is missing                               |
| Request       | `INVALID_FORMAT`       | A field has the wrong type or format                      |
| Request       | `INVALID_PRECISION`    | A numeric value has too many decimal places               |
| Request       | `NEGATIVE_VALUE`       | A value that must be non-negative is negative             |
| Request       | `VALIDATION_FAILED`    | The request failed another validation rule                |
| Signing       | `INVALID_SIGNATURE`    | Signature verification failed                             |
| Signing       | `NONCE_ALREADY_USED`   | The nonce was already processed and is not an exact retry |
| Authorization | `UNAUTHORIZED`         | The signer is not authorized for the requested action     |
| Order risk    | `VENUE_POSITION_LIMIT` | The order exceeds the venue position limit                |
| Order risk    | `WALLET_RISK_LIMIT`    | The protocol wallet is above its venue-risk limit         |
| Account       | `MARGIN_VIOLATION`     | The account has insufficient margin                       |
| Account       | `INSUFFICIENT_BALANCE` | The account has insufficient balance                      |
| State         | `INVARIANT_VIOLATION`  | The action violates a protocol business rule              |
| State         | `INVALID_STATE`        | The requested state transition is no longer valid         |
| State         | `NOT_FOUND`            | The referenced asset, market, or order was not found      |
| Venue         | `ORDER_REJECTED`       | The execution venue rejected the order                    |
| System        | `BACKPRESSURE`         | The service is under load; retry after the supplied delay |
| System        | `CIRCUIT_BREAKER_OPEN` | Trading is paused by a circuit breaker                    |
| System        | `SERVICE_UNAVAILABLE`  | A required service is temporarily unavailable             |
| System        | `INTERNAL_ERROR`       | The server encountered an unexpected error                |

## Batched Action Errors

Order, cancel, and modify results normally contain one status for each item in the request. An
individual item can fail even when the HTTP status is `200` and the top-level status is `ok`:

```json theme={null}
{
  "status": "ok",
  "response": {
    "type": "order",
    "data": {
      "statuses": [{ "resting": { "oid": "0x1a2b..." } }, { "error": "Insufficient margin" }]
    }
  }
}
```

| Action source | Result                | Meaning                                          |
| ------------- | --------------------- | ------------------------------------------------ |
| Order         | `resting` or `filled` | The order was accepted or filled                 |
| Order         | `pending`             | Venue confirmation has not completed             |
| Order         | `pendingTrigger`      | A local trigger order is waiting for its trigger |
| Order         | `pendingParentFill`   | A TP/SL child is waiting for its parent to fill  |
| Order         | `prefunding`          | A spot buy is waiting for protocol prefunding    |
| Order         | `error`               | The order was rejected                           |
| Cancel        | `success`             | The order was canceled                           |
| Cancel/modify | `error`               | The requested operation was not completed        |

Inspect every item in `response.data.statuses`. When present, `metadata.results` also contains the
Notional order ID and the corresponding status.

Some errors apply to the whole payload, such as an invalid signature, a reused nonce, or malformed
batch data. These are returned once as a request error rather than once per item. A batching client
must therefore support both a single request error and an array containing item-level errors.

## HTTP Statuses

| Status | Meaning                                     |
| ------ | ------------------------------------------- |
| `400`  | The request is malformed or incomplete      |
| `401`  | Authentication or authorization failed      |
| `422`  | The request conflicts with a semantic rule  |
| `429`  | The endpoint is temporarily rate limited    |
| `500`  | The server encountered an unexpected error  |
| `503`  | The service is busy, paused, or unavailable |

For `429` and `503`, respect the `Retry-After` header when it is present. Do not retry other `4xx`
responses without changing the request.

After a timeout, disconnect, or `500`, check the current account and order state before submitting
a new signed action. For orders, use [Open Orders](/api-reference/info-endpoints/open-orders) and
[Historical Orders](/api-reference/info-endpoints/historical-orders).

`/exchange` responses can include `X-Request-Id`, `X-Client-Request-Id`, and `X-Transaction-Id`.
Record these values when reporting an unexpected failure.