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/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.
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.tradesPerMinandlimits.requestsPerMinin GET /v1/me. Wait the number of seconds in theRetry-Afterheader (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).
detailshas 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.
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
| Code | HTTP | Retryable | Meaning |
|---|---|---|---|
VALIDATION | 400 | no | The request body or query is invalid; details.issues lists { path, message } per field. |
UNAUTHORIZED | 401 | no | Missing, malformed, wrong, expired or revoked API key. |
FORBIDDEN_IP | 403 | no | Your client has an IP allowlist and this address is not on it. |
FORBIDDEN | 403 | no | The key lacks the permission (details.permission) or the account is outside its scope. |
NOT_FOUND | 404 | no | No such account, order, key … for this key. |
CURSOR_EXPIRED | 410 | no | The event cursor is older than the 14-day retention; resync by time. |
SERVER_NOT_SUPPORTED | 422 | no | The broker server is not supported. |
BROKER_NOT_FOUND | 422 | no | No 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_VERIFIED | 409 | no | No account of the broker has logged in with its current files yet; run a check first. |
STATE_CONFLICT | 409 | no | The account or object is in a state that does not allow this. |
IDEMPOTENCY_MISMATCH | 409 | no | The Idempotency-Key was used before with a different body. |
AUTH_REJECTED | 409 | no | The broker rejected the login or password. |
MASTER_AUTH_REJECTED | 409 | no | Trading needs the master password; the one stored was rejected. |
ACCOUNT_DISABLED | 409 | no | The broker disabled the account. |
HISTORY_NOT_SYNCED | 409 | yes | History is still being downloaded; retry shortly. |
ACCOUNT_NOT_CONNECTED | 409 | yes | The account is not connected right now (use ?wait or activate it). |
MARKET_CLOSED | 423 | yes | The market for the symbol is closed. |
TRADE_REJECTED | 422 | no | The trade server rejected the request; details carry its return code. |
TRADE_NOT_ALLOWED | 422 | no | Trading is disabled for the account or symbol. |
DEADLINE_EXCEEDED | 504 | yes | The command did not finish in time; check GET /v1/commands/{id}. |
NOT_SUPPORTED_ON_PLATFORM | 422 | no | The feature does not exist on this platform (e.g. MT4 market depth). |
NOT_SUPPORTED | 501 | no | The terminal offers no way to do this. |
EA_OUTDATED | 409 | no | The feature is not available on this account's terminal yet; retry after the next gateway update. |
QUERY_TIMEOUT | 504 | yes | The terminal did not answer a read in time. |
INVALID_PRICE | 422 | no | The price is invalid for the order. |
INVALID_STOPS | 422 | no | Stop loss or take profit is invalid (too close, wrong side). |
INVALID_EXPIRATION | 422 | no | The pending order's expiration is invalid. |
INVALID_VOLUME | 422 | no | The volume is outside the symbol's min / max / step. |
ORDER_FROZEN | 422 | yes | Price or stops are inside the symbol's freeze level. |
CLOSE_BY_NOT_ALLOWED | 422 | no | Close-by is not allowed for these positions. |
SLIPPAGE | 422 | no | The price moved further than maxSlippagePoints from refPrice; the order was not sent. Do not resend it unchanged: take a new price first. |
SERVER_UNKNOWN | 422 | no | host:port matches no access point of a known server. |
SYMBOL_NOT_FOUND | 404 | no | The symbol does not exist on the account's server. |
NOT_ENOUGH_MONEY | 422 | no | Not enough free margin. |
RATE_LIMITED | 429 | yes | Too many requests this minute; wait Retry-After seconds. |
QUOTA_EXCEEDED | 403 | no | A limit is reached: registered accounts, ACTIVE accounts (details.limit / used), own keys (20), webhooks (10), risk trackers per account (10). |
SUBSCRIPTION_EXPIRED | 402 | no | Your paid period ended (details.expiresAt); renew the plan. |
CLIENT_SUSPENDED | 403 | no | Your API access is suspended (for example after a refund); contact support. Only GET /v1/me answers. |
NO_CAPACITY | 503 | yes | No capacity available right now for a new connection; retry later. |
UNAVAILABLE | 503 | yes | A gateway dependency is temporarily unavailable. |
INTERNAL | 500 | yes | Unexpected error (the message is just "internal error"); safe to retry with backoff — trade calls with the same Idempotency-Key. |