Skip to main content
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":
​
string
Always "ok" for HTTP-level success. Note that business-level errors can still appear inside response.data even when status is "ok".
​
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.
​
string
Echoes the action.type from the request. Useful for confirming which action the response corresponds to when processing responses asynchronously.
​
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.

​
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":
​
string
Always "error" for HTTP-level failures.
​
string
Server-generated request identifier. Provide this to Upside support when reporting an issue.
​
string
Machine-readable error code. See Error Codes for the full list.
​
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.

​
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.
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>"}.
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.

​
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:
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.
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.