Error Codes

All errors return a structured JSON response with isError: true and a body containing error (code), message (human-readable), and details (additional context).

Connection & Session Errors

BROKER_REJECTED_LOGON

Description: The broker explicitly rejected the FIX Logon request. The broker sends a Logout message (35=5) with a reason in tag 58 during the Logon phase. Common Reasons:

• RET_INVALID_DATA — wrong FIX API password or invalid credentials
• RET_NOT_ALLOWED — FIX API not enabled for this account
• RET_ACCOUNT_DISABLED — account suspended or disabled

Resolution:

1. Verify your FIX API password (it’s separate from your cTrader account password)
2. Reset the FIX API password in cTrader → Settings → FIX API
3. Verify the SenderCompID matches your account
4. Confirm the FIX host matches the server your account is registered on
5. Ensure FIX API access is enabled for your account with the broker

FIX_NOT_READY

Description: FIX connection is not established or not in ACTIVE state. Common Causes:

• Server just started and FIX connection is still initializing
• Network issue preventing TCP/TLS connection
• Invalid credentials causing Logon rejection
• Broker gateway is down or in maintenance

Resolution:

1. Wait 10-30 seconds for connection to establish
2. Check ctrader://health resource for FIX state
3. Verify your FIX credentials (host, port, SenderCompID, password)
4. Test connectivity to the FIX host and port
5. Verify TLS is working on the FIX connection
6. Confirm FIX API is enabled for your account with the broker

CREDENTIAL_REJECTED

Description: The broker rejected the provided credentials during connection. Common Causes:

• Incorrect FIX API password (note: this is separate from your cTrader account password)
• Wrong SenderCompID
• FIX API not enabled for the account
• Wrong server selected

Resolution: Re-authorize with correct credentials. Check your FIX API settings in cTrader.

BROKER_UNREACHABLE

Description: Could not establish a connection to the broker during credential validation (e.g. the FIX gateway timed out or refused the connection). Common Causes:

• Wrong server selected
• Broker gateway is temporarily down or in maintenance
• Network connectivity issues

Resolution: Verify server selection and try again shortly. If persistent, check broker status. This is a transient connection error — it does not mean your credentials are wrong, and it does not lock your account or revoke tokens. Authentication simply returns this error so you can retry once the trading gateway is reachable again.

RECONNECTING

Description: FIX connection was lost and the server is attempting to reconnect. Resolution: Wait for reconnection to complete (automatic). Check network stability.

RECONCILING

Description: Post-logon state reconciliation is in progress. Resolution: Wait 5-10 seconds for reconciliation to complete. The server is syncing positions and orders with the broker.

Risk Management Errors

RISK_CHECK_FAILED

Description: One of the 8 risk checks rejected the order. Details field includes: reason, current values vs. limits, and a suggestion for fixing. Common Reasons:

• Daily loss limit exceeded
• Maximum position size exceeded
• Maximum open positions reached
• Volume below minimum or not a valid step

Resolution: Follow the suggestion field in the error details. Common fixes:

• Wait for daily PnL reset (17:00 New York time, DST-adjusted)
• Reduce order volume
• Close existing positions

KILL_SWITCH_ACTIVE

Description: Emergency kill switch is active, blocking ALL trading. Details field includes: reason for activation, timestamp, deactivation instructions. Common Causes:

• Daily loss limit exceeded
• State reconciliation detected discrepancies (circuit breaker)

Resolution:

1. Call check_health to see the kill switch status and activation reason
2. Check daily PnL via ctrader://health resource
3. The daily loss trigger auto-resets at 17:00 New York time (DST-adjusted)

RATE_LIMITED

Description: Too many orders submitted within a short window. Field Data Includes: Limit type, wait duration (sec), and retry timestamp. Common Causes:

• More than 2 orders per second
• More than 10 orders per minute (configurable)
• Less than 5 seconds between orders on the same symbol

Resolution: Wait the number of seconds specified in waitSeconds.

MODE_RESTRICTED

Description: Current operating mode does not allow this operation. Common Cause: Trying to place/modify/cancel orders in readonly mode. Resolution: Switch mode to paper (for testing) or live (for real trading).

Validation Errors

INVALID_SYMBOL

Description: Symbol is not recognized or not in the allowed list. Resolution: Check the symbol catalog via get_symbols tool. Symbol names must be uppercase alphanumeric (3-10 characters).

INVALID_VOLUME

Description: Volume is outside acceptable range or not a valid step. Resolution: Check symbol’s lot size, minimum volume, and volume step.

INVALID_PRICE

Description: Price value is invalid or out of range. Resolution: Verify price is positive and within reasonable bounds.

INVALID_PARAMS

Description: Request parameters failed validation. Resolution: Check parameter types and required fields. LIMIT orders need price, STOP orders need stopPrice. Note: STOP_LIMIT is not supported by the broker.

Order & Position Errors

ORDER_REJECTED

Description: The broker rejected the order. Details: Contains the broker’s rejection reason. Resolution: Review the rejection reason. Common: insufficient margin, market closed, symbol not available.

Market Closed Rejection: If the rejection reason indicates the market is closed, MARKET orders cannot be executed because there is no active session for immediate fills. However, you can still place pending orders that will activate when the market reopens:

• LIMIT order — queued at your specified price, fills when market opens and price matches
• STOP order — triggers a market order when the stop price is reached after market open

Use timeInForce: "GTC" (Good Till Cancel) so the order persists across sessions.

ORDER_NOT_FOUND

Description: No pending order found with the given orderId or clOrdId. Resolution: Verify the order ID. The order may have already been filled or cancelled. Use get_positions or ctrader://orders to check current state.

POSITION_NOT_FOUND

Description: No open position found with the given positionId. Resolution: Verify the position ID. Use get_positions to list current positions. The position may have already been closed.

MODIFY_FAILED

Description: Order modification request was rejected. Resolution: Ensure the order is still pending (not filled/cancelled).

CANCEL_FAILED

Description: Order cancellation request was rejected. Resolution: Ensure the order is still pending. Cannot cancel filled orders.

CLOSE_FAILED

Description: Position close request failed. Resolution: Verify position exists and volume is valid.

Protocol & Timeout Errors

TIMEOUT

Description: FIX response not received within the timeout period. Resolution: Check FIX connection state. The broker may be slow to respond. Retry the operation after verifying connection status.

FIX_PROTOCOL_ERROR

Description: Unexpected FIX protocol error. Resolution: Review server logs for details. May indicate a protocol mismatch.

BROKER_REJECTED

Description: The broker explicitly rejected the request. Resolution: Review the rejection reason in the error details.

Internal Errors

INTERNAL_ERROR

Description: Unexpected server-side error. Resolution: Review server logs. This may indicate a bug.

LOCK_TIMEOUT

Description: Could not acquire the trade lock within the timeout period. Resolution: A previous trading operation is taking too long. Wait and retry. This may happen under heavy load or if a FIX response is delayed.