Errors

Every failure has the same shape:

{
  "error": {
    "code": "ACCOUNT_EXECUTING",
    "message": "An order is in flight. Stopping now would leave its outcome unknown.",
    "details": []
  },
  "requestId": "3f8a1c92-7b4e-4d81-a2f6-0c5e9b3d7a14"
}

Match on code. It is stable across releases. message is written for a human and will change. details appears on validation failures and names the fields; on a failed order, details[0] carries its orderId, state and retryable.

requestId is on every error response, and is recorded against every audit row. Quote it in a support request and the entire call can be found.

The codesCopy Anchor Link

Authentication and authorizationCopy Anchor Link

One code for every authentication failure is intentional: distinguishing "unknown key" from "wrong secret" lets someone with a list of candidate keys sort the real from the fake. See Authentication.

MCP sign-inCopy Anchor Link

/mcp and /mcp/insights answer a connected app's request with a WWW-Authenticate challenge rather than one of the codes above:

See MCP server for what triggers each one.

RequestsCopy Anchor Link

ACCOUNT_NOT_FOUND is also what you get for an account that exists but belongs to somebody else. Returning 403 would confirm that a guessed id is real. POST /v1/accounts/{id}/password, POST /v1/accounts/{id}/server and DELETE /v1/accounts/{id} answer a missing account with NOT_FOUND rather than ACCOUNT_NOT_FOUND; treat the two the same.

Rate limitsCopy Anchor Link

Limits are per workspace and per class of work, so polling never spends the budget your orders need. Each is a steady rate per minute plus a short burst.

Every response names its class in x-ratelimit-class and the ceiling in x-ratelimit-limit. Console sessions have buckets of their own.

AccountsCopy Anchor Link

TradingCopy Anchor Link

422 rather than 400 for a rejection: the request was well formed and we understood it. The broker declined it, which is a different problem with a different fix.

ORDER_UNRESOLVED is the one to handle deliberately. See Trading and history.

PlansCopy Anchor Link

BillingCopy Anchor Link

InstrumentsCopy Anchor Link

Multi-account ordersCopy Anchor Link

Copy tradingCopy Anchor Link

None of these is retryable as sent: each names something about the strategy, subscription or account that the request itself must change first.

TradingView alert hooksCopy Anchor Link

These are returned to TradingView by the hook URL, and recorded in the hook's log.

Webhooks and eventsCopy Anchor Link

Console, keys and membersCopy Anchor Link

Signing in itself (/auth, used by the console) answers in its own shape, { code, message }:

LifecycleCopy Anchor Link

NEEDS_OPERATOR deserves emphasis. Do not retry it, and do not put it in a loop with a backoff. Repeated failed logins are how a broker locks an account, and at that point fixing the password is no longer enough. Surface it to whoever owns the credentials.

RetryingCopy Anchor Link

Decide by code, not by status. Retry 500, and a 503 whose code is not ORDER_UNRESOLVED, with exponential backoff and jitter. Never retry ORDER_UNRESOLVED — poll the order. Do not retry 4xx, except 429 after its retry-after; nothing else about the request will have improved. Do not retry 501 CAPABILITY_UNAVAILABLE either: the answer changes only when the account's terminal is updated.

Why 503, not 502. Every failure that is ours rather than yours — SEND_FAILED, ORDER_UNRESOLVED, SCHEDULER_FAILED, RESTART_FAILED, PROVIDER_ERROR — answers 503 with the JSON body. Until 3 October 2026 these were 502, and the network edge in front of the API replaced every 502 body with its own text, so a client could not tell a safe resend from one that must never happen. If you branched on 502, branch on code.

import random, time

def retryable(response):
    if response.status_code == 500:
        return True
    if response.status_code == 503:
        # SEND_FAILED is proven never to have reached the broker. ORDER_UNRESOLVED
        # may have executed: poll the order, never resend.
        return response.json().get("error", {}).get("code") != "ORDER_UNRESOLVED"
    return False

def call_with_retry(send, attempts=5):
    # For an order, `send` must carry the same Idempotency-Key on every attempt.
    for attempt in range(attempts):
        response = send()
        if not retryable(response):
            return response
        if attempt == attempts - 1:
            return response
        # Jitter, not a fixed schedule: every client backing off in lockstep
        # arrives together and reproduces the load that caused the failure.
        time.sleep(min(2 ** attempt, 30) * (0.5 + random.random()))
    raise AssertionError("unreachable")

Even a retried ORDER_UNRESOLVED is harmless when it carries the same Idempotency-Key: the key stays claimed and the same answer comes back. What must never happen is a resend under a new key.

The lifecycle 503s — SCHEDULER_FAILED, RESTART_FAILED — involve no order and are safe to retry with backoff too.

warm (bring online) is safe to retry as-is: a second call to an account that is already online returns alreadyRunning: true.

Order placement is not safe to retry blindly. Send an Idempotency-Key with every order: a retry with the same key returns the first result instead of placing a second trade. Retrying without one is the one place in this API where a careless retry costs money.

When the state, not the status, is the errorCopy Anchor Link

A 202 from warm means we accepted the work, not that it succeeded. The login can still fail afterwards, and it reports through the account's state rather than through an HTTP status nobody is listening to any more.

Poll GET /v1/accounts/{id}/status and treat invalid_credentials, needs_2fa, needs_certificate and trading_disabled as failures. Accounts and lifecycle has a polling loop that handles this correctly.