API Fundamentals

Response Format

All API responses follow a consistent envelope:

{
  "data": ...,
  "error": null,
  "metadata": {
    "request_id": "523be14bfc539676885a2ef4629e5322",
    "page_number": 1,
    "total_items": 560,
    "total_pages": 6,
    "next_page_token": "AAAAAAAAAGQAAAAAAAAAZA",
    "previous_page_token": null
  }
}

• data contains the response payload — a single object for detail endpoints, an array for list endpoints.
• error is null on success. On failure, it contains a structured error object.
• metadata always includes request_id. Pagination fields appear only on list endpoints.

Pagination

Endpoints support page_size and page_token query parameters:

GET /v1/accounts/{account_id}/orders?page_size=6&page_token=AAAAAAAAAGQAAAAAAAAAZA

The response metadata includes page_number, total_items, total_pages, next_page_token, and previous_page_token to help you navigate through results.

"metadata": {
       "request_id": "523be14bfc539676885a2ef4629e5322",
       "page_number": 1,
       "total_items": 560,
       "total_pages": 6,
       "next_page_token": "AAAAAAAAAGQAAAAAAAAAZA"
   }

Error Codes

When an error occurs, the response includes a structured error in the error field as shown with a code along with a descriptive message.

{
  "error": {
    "code": 422,
    "message": "Invalid limit price: must be positive"
  },
  "metadata": {
    "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

Common HTTP Status Codes

Code	Meaning
200	Success
400	Bad request — the request body or query parameters failed validation. Inspect error.message for the specific field and reason; correct and retry.
401	Unauthorized — the Authorization header is missing or contains an invalid or expired API key. Generate a new key in the web app and retry.
403	Forbidden — the API key is valid but lacks permission for this account or action. Verify the account ID and the key’s scope; contact support if access should be granted.
404	Not found — the requested account, order, or resource does not exist or is not visible to this API key. Verify the ID in the path.
422	Unprocessable — the request was syntactically valid but rejected by a downstream check (e.g., risk, buying power, restricted list). The error.code field identifies the specific rejection reason; see the Order Rejection Reasons reference.
500	Internal server error — an unexpected failure occurred on the server. Retry with exponential backoff. If the problem persists, contact support and include the request_id from the response metadata.

---