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

# Upside API Response Formats: Success and Errors

> Reference for success and error response shapes from POST /exchange and POST /info, including business-level errors inside the statuses array.

Upside returns JSON for every request. Understanding the response structure is important because **HTTP 200 does not always mean the operation succeeded** — business-level rejections (such as invalid order prices or unknown order IDs) return HTTP 200 with error detail inside the response body. This page explains every response shape you may encounter.

## POST /exchange Success Response

When a write operation is accepted and processed, the server returns HTTP 200 with `status: "ok"`:

```json theme={"system"}
{
  "status": "ok",
  "requestId": "req-144115188075855905",
  "response": {
    "type": "order",
    "data": {
      "statuses": [
        {
          "resting": {
            "oid": 15
          }
        }
      ]
    }
  }
}
```

<ResponseField name="status" type="string">
  Always `"ok"` for HTTP-level success. Note that business-level errors can still appear inside `response.data` even when `status` is `"ok"`.
</ResponseField>

<ResponseField name="requestId" type="string">
  A server-generated unique identifier for this request. Include this value when contacting Upside support — it allows the team to trace the request through server logs.
</ResponseField>

<ResponseField name="response.type" type="string">
  Echoes the `action.type` from the request. Useful for confirming which action the response corresponds to when processing responses asynchronously.
</ResponseField>

<ResponseField name="response.data" type="object">
  Action-specific result data. For `order` actions this contains a `statuses` array. For `registerAccount` this contains `accountId`. See each action's reference page for the full data shape.
</ResponseField>

## POST /exchange Error Response

When the server rejects the request at the HTTP level (bad signature, malformed JSON, rate limit, etc.), it returns a non-200 HTTP status with `status: "error"`:

```json theme={"system"}
{
  "status": "error",
  "requestId": "req-144115188075855906",
  "code": "SIGNATURE_INVALID",
  "message": "recovered address 0xabc...def does not match action.address 0x123...456"
}
```

<ResponseField name="status" type="string">
  Always `"error"` for HTTP-level failures.
</ResponseField>

<ResponseField name="requestId" type="string">
  Server-generated request identifier. Provide this to Upside support when reporting an issue.
</ResponseField>

<ResponseField name="code" type="string">
  Machine-readable error code. See [Error Codes](/guide/error-codes) for the full list.
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable explanation of the error. For `SIGNATURE_INVALID`, this includes both the recovered address and the expected address to help you debug signing issues.
</ResponseField>

## Business-Level Errors

Some operations return HTTP 200 with `status: "ok"` but contain per-item errors inside `response.data.statuses`. This occurs when the request envelope is valid and signed correctly, but one or more of the operations within the request was rejected by the matching engine.

```json theme={"system"}
{
  "status": "ok",
  "requestId": "req-144115188075855907",
  "response": {
    "type": "order",
    "data": {
      "statuses": [
        {
          "error": "size must be positive"
        }
      ]
    }
  }
}
```

Each entry in `statuses` corresponds to one item in the request's array (e.g. one entry per order in `orders[]`). A successful item looks like `{"resting": {"oid": 15}}` or `{"filled": {...}}`. A rejected item looks like `{"error": "<message>"}`.

<Warning>
  Always check the `statuses` array in order and cancel responses. An HTTP 200 response does not guarantee that any or all operations within the request succeeded. Iterate over `statuses` and handle each `error` entry explicitly.
</Warning>

## POST /info Response

Read query responses return HTTP 200 with the query result directly in the body. There is no wrapper `status` field — the body IS the data:

```json theme={"system"}
[
  {
    "oid": 15,
    "asset": 1,
    "isBuy": true,
    "limitPx": "50",
    "sz": "10",
    "tif": "Gtc"
  }
]
```

If the query fails (bad `type`, missing required fields), the server returns a non-200 status with an error body consistent with the exchange error format.

## The requestId Field

Every `POST /exchange` response includes a `requestId` such as `"req-144115188075855905"`. This is a globally unique identifier generated by the server for each incoming request. When you contact Upside support about a specific request — whether it succeeded unexpectedly, failed unexpectedly, or produced a surprising result — including the `requestId` allows the support team to locate the exact request in server logs and investigate efficiently.

<Tip>
  Log the `requestId` for every `POST /exchange` call your application makes. Even if you don't need it immediately, having it available significantly speeds up any future debugging or support conversations.
</Tip>