Errors

Every error has the same shape:

{
  "error": "bad_request",
  "message": "XAUUSD is not available on this account",
  "details": { "hint": "GET /v1/accounts/:id/symbols lists what this account can trade." },
  "requestId": "3f8a2b19-4c1e-4b7a-9d0e-8a2c1f6b3e55"
}

Branch on error: it is stable. message is for people and its wording can improve. details.hint, when present, tells you what to do next.

error	HTTP	Cause	Retry?
bad_request	400	Invalid body, an unknown symbol, a broker that does not match the server.	No. Fix the request.
unauthorized	401	Missing, unknown or revoked credential.	No.
forbidden	403	A read-only key or a viewer trying to trade, or a team you are not in.	No.
not_found	404	No such resource, including one that belongs to someone else.	No.
conflict	409	An idempotency key still in flight, or an account still connecting.	Yes, after a pause.
plan_limit	409	More accounts or live sessions than your plan allows.	No.
login_failed	409	Your broker refused the account's login, server or password. The account's status says login_failed until it connects.	No. Disconnect it and connect it again with the right details.
server_unknown	409	We have not reached this account's server yet and are finding it. The account's status says adding meanwhile.	In a few minutes. If it persists, check the server name.
rate_limited	429	Over your requests per second. Carries Retry-After.	Yes.
upstream_failed	502	We could not reach your broker, or we are too busy starting accounts right now.	Sometimes.
internal	500	Our fault.	Yes, and send us the requestId.

Request IDs

Every response carries an x-request-id header, and every error repeats it as requestId. Send your own x-request-id and we use yours, which makes it easy to line up our logs with yours. Quote it when you contact us about a specific call.

Not errors

Some answers look like failures and are not. Treat them as states:

Response	Means
A notice on a connect response	The account was saved but cannot connect yet. Show the text.
connectable: false on a broker	You can add accounts; they connect once we finish setting the broker up.
pending entries in a bulk close	The broker accepted those closes and has not confirmed them yet. Re-read positions.
tradable: false on a symbol	A real symbol that is not taking orders right now.
Order result with ok: false and "Position limit reached"	Your broker caps open positions. Close some first; retrying will not help.