Errors and limits

Error envelope

Every error returns a stable machine code, a safe message, and the request ID:

1234567{
    "error": {
        "code": "account_disabled",
        "message": "The connected account is disabled",
        "requestId": "6c9e4a3e-..."
    }
}

Keep the requestId when reporting a problem; it identifies the exact request on our side.

Error codes

Code	Meaning
`invalid_request`	Malformed body, parameters, cursor, or missing headers
`invalid_api_key`	The key is missing, malformed, revoked, or expired
`insufficient_scope`	The key lacks the scope this endpoint requires
`subscription_required`	The workspace does not have an active trial or subscription
`account_not_found`	No such account in your tenant
`account_disabled`	The account exists but reads are revoked
`server_not_found`	MT5 verified the server name does not resolve
`broker_unreachable`	The broker could not be reached; not a credential failure
`credentials_rejected`	The broker rejected the credentials; only used after a real broker response
`capacity_exhausted`	No worker capacity inside the request deadline
`request_timeout`	The request exceeded its deadline while being served
`terminal_unhealthy`	The MT5 terminal failed in a way that is not your fault
`conflict`	The request conflicts with concurrent state
`control_plane_unavailable`	A transient control-plane failure remained after one read retry
`internal_error`	Unexpected failure; safe to report with the request ID

Two guarantees worth relying on: credentials_rejected is never used when FiveSocket failed to reach the broker, and server_not_found is never used for a transient terminal failure. A negative answer always means a verified negative. A single rejected login is never enough: credentials_rejected is returned only after two consecutive rejections of the same credentials on healthy workers, so a broker refusing a login burst is retried instead of reported as a wrong password.

Retries

capacity_exhausted returns 503 with a bounded Retry-After header. Honor it.
rate_limit_exceeded returns 429 with Retry-After and the current rate-limit headers.
subscription_required returns 402; start or restore the subscription in the control surface.
control_plane_unavailable returns 503 with Retry-After after one bounded internal retry of a read. Mutations are not internally retried.
A request that begins serving but exceeds its deadline returns 504. The worker session is fenced and destroyed, so the read either fully happened or fully did not.
Client mistakes return 4xx and are never worth retrying unchanged.

Idempotency

POST /v1/accounts and DELETE /v1/accounts/{accountId} require an Idempotency-Key header. Reuse the same key when retrying the same logical operation.

Pagination

GET /v1/accounts/{accountId}/trades, deals, and orders use opaque signed cursors. Pass the nextCursor value back verbatim; cursors are bound to the account and query window, and a tampered or foreign cursor is rejected as invalid_request.

Window rules:

initial reads require an explicit to; missing it returns 400 invalid_request
from defaults deterministically to 30 days before to
cursor requests omit from and to because the cursor carries both bounds
the window cannot exceed 90 days
limit is 1 to 1000, default 100

Limits

V1 enforces limits per tenant, API key, and connected account:

request rate and concurrent requests
concurrent logins per account
maximum trade-history interval and page size
maximum request deadline
request bodies over 32 KB are rejected

Limits protect the shared worker pool. They do not create freshness tiers; every read that succeeds is a live read.

The current per-minute policies are:

Plan	API key	Workspace	Connected MT5 account
Starter	60	120	30
Plus	120	300	30
Scale	300	1,000	60

Every metered success includes RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset. The values describe the applicable bucket with the least remaining capacity. Cached history cursor pages do not consume the live MT5 account bucket.