API documentation

Errors & limits

Every error has the same JSON body and a stable code. Use the code — not the message — in your logic, and retry only what is marked retryable.

Updated

Error body

The HTTP status tells the class of problem, the body tells exactly which:

http
HTTP/1.1 429 Too Many Requests
Retry-After: 17
X-Request-Id: 3f1c2a9e-7b4d-4e8a-9c21-5d6e7f809a1b

{
  "code": "RATE_LIMITED",
  "message": "rate limit exceeded",
  "retryable": true,
  "details": { "retryAfter": 17 },
  "requestId": "3f1c2a9e-7b4d-4e8a-9c21-5d6e7f809a1b"
}

Every response carries an X-Request-Id header and every error body the same requestId: quote it when you contact support. You may send your own X-Request-Id (8–64 letters, digits, . _ -); otherwise one is generated.

message is for people and may change; details carries machine-readable extras (the fields that failed validation, the permission needed, retryAfter, limit / used, syncedUntil …). A failed trade command answers its own code (TRADE_REJECTED, NOT_ENOUGH_MONEY …) with what the terminal reported in details.

json
400 Bad Request
{
  "code": "VALIDATION",
  "message": "invalid input",
  "retryable": false,
  "details": { "issues": [ { "path": "volume", "message": "Number must be greater than 0" } ] }
}

Limits, quotas and your plan

  • 429 RATE_LIMITED — too many requests this minute. Trade calls and all other calls have separate per-minute limits for your whole account (all keys together): limits.tradesPerMin and limits.requestsPerMin in GET /v1/me. Wait the number of seconds in the Retry-After header (the next minute). Too many failed authentications from one address also answer 429 for the rest of the minute.
  • 403 QUOTA_EXCEEDED — a limit is reached: registered accounts (POST /v1/accounts), ACTIVE accounts (POST …/activate), your own keys (20), webhooks (10) or risk trackers per account (10). details has limit and, for accounts, used. Deactivate or remove something, or move to a bigger plan.
  • 402 SUBSCRIPTION_EXPIRED — the paid period ended (details.expiresAt). Every route answers 402 except GET /v1/me, GET …/positions, GET …/orders, POST …/positions/{positionId}/close, DELETE …/orders/{orderId}, POST …/close-all and the billing reads (GET /v1/billing/invoices, …/invoices/{id}, …/usage) — so you can still see and flatten open trades. GET /v1/commands/{id} and GET /v1/events answer 402 as well: send those close calls with ?wait, or repeat them with the same Idempotency-Key, to read their result. WebSockets close (4401) and new ones are refused (401); webhooks pause. After a grace period your ACTIVE accounts go to STANDBY. Renew the plan to continue — your keys and accounts stay the same.
  • 403 CLIENT_SUSPENDED — your access is suspended (for example after a refund). Only GET /v1/me answers; contact support.
Your current limits and usage are in GET /v1/me and in Account → API; every answer carries the header x-subscription-expires-at. The events SUBSCRIPTION_EXPIRING (3 days and 1 day before) and SUBSCRIPTION_EXPIRED arrive in your event feed, WebSocket and webhooks.

Retrying safely

Retry when retryable is true, with exponential backoff (and Retry-After for 429). Retry trade calls with the same Idempotency-Key, so a retried order is never placed twice.

async function call<T>(fn: () => Promise<Response>): Promise<T> {
  for (let attempt = 0; ; attempt++) {
    const res = await fn();               // trade calls: keep the same Idempotency-Key in fn
    if (res.ok) return res.json();
    const err = await res.json();
    if (!err.retryable || attempt >= 3) throw err;
    const wait = Number(res.headers.get("retry-after")) || 2 ** attempt;
    await new Promise((r) => setTimeout(r, wait * 1000));
  }
}

All error codes

CodeHTTPRetryableMeaning
VALIDATION400noThe request body or query is invalid; details.issues lists { path, message } per field.
UNAUTHORIZED401noMissing, malformed, wrong, expired or revoked API key.
FORBIDDEN_IP403noYour client has an IP allowlist and this address is not on it.
FORBIDDEN403noThe key lacks the permission (details.permission) or the account is outside its scope.
NOT_FOUND404noNo such account, order, key … for this key.
CURSOR_EXPIRED410noThe event cursor is older than the 14-day retention; resync by time.
SERVER_NOT_SUPPORTED422noThe broker server is not supported.
BROKER_NOT_FOUND422noNo broker of that name and platform is available to you — check GET /v1/brokers, or ask us to add it with POST /v1/broker-requests.
BROKER_NOT_VERIFIED409noNo account of the broker has logged in with its current files yet; run a check first.
STATE_CONFLICT409noThe account or object is in a state that does not allow this.
IDEMPOTENCY_MISMATCH409noThe Idempotency-Key was used before with a different body.
AUTH_REJECTED409noThe broker rejected the login or password.
MASTER_AUTH_REJECTED409noTrading needs the master password; the one stored was rejected.
ACCOUNT_DISABLED409noThe broker disabled the account.
HISTORY_NOT_SYNCED409yesHistory is still being downloaded; retry shortly.
ACCOUNT_NOT_CONNECTED409yesThe account is not connected right now (use ?wait or activate it).
MARKET_CLOSED423yesThe market for the symbol is closed.
TRADE_REJECTED422noThe trade server rejected the request; details carry its return code.
TRADE_NOT_ALLOWED422noTrading is disabled for the account or symbol.
DEADLINE_EXCEEDED504yesThe command did not finish in time; check GET /v1/commands/{id}.
NOT_SUPPORTED_ON_PLATFORM422noThe feature does not exist on this platform (e.g. MT4 market depth).
NOT_SUPPORTED501noThe terminal offers no way to do this.
EA_OUTDATED409noThe feature is not available on this account's terminal yet; retry after the next gateway update.
QUERY_TIMEOUT504yesThe terminal did not answer a read in time.
INVALID_PRICE422noThe price is invalid for the order.
INVALID_STOPS422noStop loss or take profit is invalid (too close, wrong side).
INVALID_EXPIRATION422noThe pending order's expiration is invalid.
INVALID_VOLUME422noThe volume is outside the symbol's min / max / step.
ORDER_FROZEN422yesPrice or stops are inside the symbol's freeze level.
CLOSE_BY_NOT_ALLOWED422noClose-by is not allowed for these positions.
SLIPPAGE422noThe price moved further than maxSlippagePoints from refPrice; the order was not sent. Do not resend it unchanged: take a new price first.
SERVER_UNKNOWN422nohost:port matches no access point of a known server.
SYMBOL_NOT_FOUND404noThe symbol does not exist on the account's server.
NOT_ENOUGH_MONEY422noNot enough free margin.
RATE_LIMITED429yesToo many requests this minute; wait Retry-After seconds.
QUOTA_EXCEEDED403noA limit is reached: registered accounts, ACTIVE accounts (details.limit / used), own keys (20), webhooks (10), risk trackers per account (10).
SUBSCRIPTION_EXPIRED402noYour paid period ended (details.expiresAt); renew the plan.
CLIENT_SUSPENDED403noYour API access is suspended (for example after a refund); contact support. Only GET /v1/me answers.
NO_CAPACITY503yesNo capacity available right now for a new connection; retry later.
UNAVAILABLE503yesA gateway dependency is temporarily unavailable.
INTERNAL500yesUnexpected error (the message is just "internal error"); safe to retry with backoff — trade calls with the same Idempotency-Key.