API Reference

Errors & Limits

How the API reports problems, how lists paginate, and how to build clients that fail gracefully.

Error shape

Errors return a JSON body with a detail field — a string for simple errors, or a structured list for validation errors:

401 · unauthorized

{
  "detail": "Could not validate credentials"
}

422 · validation error

{
  "detail": [
    {
      "loc": ["query", "action"],
      "msg": "string does not match regex \"^(BUY|SELL|HOLD)$\"",
      "type": "value_error.str.regex"
    }
  ]
}

Status codes

Code	Meaning	What to do
`200 / 201`	Success / created	—
`400`	Bad request	Fix the request; the detail explains what was wrong
`401`	Missing, invalid, or expired token	Refresh the access token and retry once
`403`	Authenticated but not allowed	E.g. unverified email or insufficient access — not retryable
`404`	Resource not found	Check IDs/symbols; a closed position is a 404, not an error
`422`	Validation failed	Fix the listed fields
`429`	Rate limited	Back off and retry with exponential delay
`500 / 502 / 503 / 504`	Server or upstream issue	Retry with backoff; these are transient

Pagination conventions

Two styles exist, by endpoint family:

Page-based (trading lists — orders, trades): page (from 1) and page_size (default 50, max 1000). Responses include total, page, page_size, and pages.
Offset-based (decisions feed): limit (1–200, default 50) and offset. The response total respects your filters.

Rate limits

The gateway enforces per-user rate limits to keep the platform responsive for everyone. Limits are generous for normal application use; bulk backfills should be throttled client-side. On 429, honour any Retry-After header, otherwise back off exponentially (1s, 2s, 4s, …).

Building a resilient client

Refresh on 401 once, then re-authenticate fully if refresh also fails.
Treat 403 as a state to surface to the user (e.g. verification required), not a retry case.
Retry 5xx and 429 with backoff and a retry cap; never retry 4xx blindly.
Parse monetary fields as decimals/strings — never as floating-point binary.
Log the detail field; it is written to be actionable.

Stuck? Include a Reference ID

For anything decision-related, the decision's Reference ID (from the app or the decisions API) lets support reconstruct the exact event instantly.