Order Responses

Each order passes through several validation layers before potentially becoming an active order in the market. Each layer serves a specific purpose and helps maintain the integrity and safety of the trading system. A 400 response indicates non-normal operations, suggesting that an operator should be alerted to the error and/or a client system fix should be considered.

Validation Layers

Stateless Validation

The first layer of defense occurs at the API gateway level. This validation checks basic order properties without requiring any market context or state:

• Input format and data types
• Required field presence
• Character limits and encoding
• Basic business rule violations
• Authentication status

Failures at this layer return immediate 400 (Invalid Request) or 401 (Unauthorized) responses without creating any orders.

Stateful Validation

Once an order passes basic validation, it enters the engine where it undergoes checks that require current market state:

• Instrument existence and status
• Account status and permissions
• Price and quantity limits
• Duplicate order checks
• Instrument-specific rules

These checks create a command but reject invalid orders before creating an order.

Market Validation

Orders that pass stateful validation undergo final market-level checks:

• Margin requirements
• Risk limits
• Fill-or-kill conditions
• Post-only conditions
• Market liquidity conditions

These checks create both commands and orders, but may result in immediate cancellation if market conditions aren't met.

Activation Layer

Some order types remain in an inactive state until specific conditions are met:

• Stop orders (waiting for price trigger)
• Contingent orders (OneTriggersTheOther, OneCancelsTheOther)

These orders undergo additional market validation when their activation conditions are met before becoming active in the order book.

Understanding API Responses

The validation layer that processes an order determines the type of response:

1. Stateless validation failures return immediately with no order creation
2. Stateful validation failures create a command but no order
3. Market validation failures create both commands and orders, with a cancellation
4. Activation layer adds additional states for orders waiting to be triggered

flowchart TD
    A["Order Submitted"] --> B{"Stateless\nValidation"}
    B -- Fail --> C["400/401 Response"]
    B -- Pass --> D{"Stateful\nValidation"}
    D -- Fail --> E["400 Response\nCommand Created"]
    D -- Pass --> F{"Order Type"}
    F -- Regular Order --> G{"Margin and Risk\nValidation"}
    F -- Stop/Trigger Order --> H["Inactive State"]
    H --> Q["200 Response"] & I{"Trigger\nCondition Met"}
    L["Active Order"] --> S["200 Response"] & M{"Execution"}
    I -- Yes --> G
    I -- No --> J["Wait for Trigger"]
    J --> I
    G -- Fail Margin & Risk --> K["Order Cancelled"]
    G -- Fail Market --> U["Order Cancelled"]
    K --> T["400 Response"]
    U --> V["200 Response"]
    G -- Pass --> L
    M -- Full Fill --> N["Order Complete"]
    M -- Partial Fill --> O["Remaining Open or Cancelled"]
    M -- No Fill --> P["Order Open or Cancelled"]

     B:::validation
     C:::response
     D:::validation
     E:::response
     G:::validation
     H:::state
     Q:::response
     L:::state
     S:::response
     K:::state
     U:::state
     T:::response
     V:::response
     N:::state
     O:::state
     P:::state
    classDef validation fill:#f9f,stroke:#333,stroke-width:2px
    classDef response fill:#bbf,stroke:#333,stroke-width:2px
    classDef state fill:#bfb,stroke:#333,stroke-width:2px