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
`account_not_found`	No such account in your tenant
`account_disabled`	The account exists but reads are revoked
`server_not_verified`	The server name has not passed verification
`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
`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.

Retries

capacity_exhausted returns 503 with a bounded Retry-After header. Honor it.
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 uses 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:

to defaults to now, from defaults to 30 days before to
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.