> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kalshi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Handling

> Understanding and handling errors on margin FIX sessions

## Overview

Margin FIX uses standard FIX error messages with additional detail in the Text field. Errors fall into two categories:

* **Session-level errors**: Protocol violations, handled with Reject (35=3)
* **Business-level errors**: Application logic issues, handled with BusinessMessageReject (35=j) or order-specific rejection messages

## Error Message Types

### Reject (35=3)

Used for session-level protocol violations.

| Tag | Name                | Description                         | Required |
| --- | ------------------- | ----------------------------------- | -------- |
| 45  | RefSeqNum           | Sequence number of rejected message | Yes      |
| 58  | Text                | Human-readable error description    | No       |
| 371 | RefTagID            | Tag that caused the rejection       | No       |
| 372 | RefMsgType          | Message type being rejected         | No       |
| 373 | SessionRejectReason | Rejection reason code               | No       |

#### Session Reject Reasons (373)

| Code | Reason                      | Description                                          |
| ---- | --------------------------- | ---------------------------------------------------- |
| 0    | Invalid tag number          | Unknown tag in message                               |
| 1    | Required tag missing        | Mandatory field not present                          |
| 2    | Tag not defined for message | Tag not valid for this message type                  |
| 3    | Undefined tag               | Tag number not in FIX specification                  |
| 4    | Tag without value           | Empty tag value                                      |
| 5    | Incorrect value             | Invalid value for tag                                |
| 6    | Incorrect data format       | Wrong data type                                      |
| 8    | Signature problem           | Authentication failure                               |
| 9    | CompID problem              | SenderCompID/TargetCompID issue                      |
| 10   | SendingTime accuracy        | SendingTime must be within 30 seconds of server time |
| 11   | Invalid MsgType             | Unknown message type                                 |

### BusinessMessageReject (35=j)

Used for application-level business logic errors.

| Tag | Name                 | Description                         | Required |
| --- | -------------------- | ----------------------------------- | -------- |
| 45  | RefSeqNum            | Sequence number of rejected message | Yes      |
| 58  | Text                 | Human-readable error description    | No       |
| 372 | RefMsgType           | Message type being rejected         | Yes      |
| 379 | BusinessRejectRefID  | Business ID from rejected message   | No       |
| 380 | BusinessRejectReason | Business rejection reason code      | Yes      |

#### Business Reject Reasons (380)

| Code | Reason                               | Description                                         |
| ---- | ------------------------------------ | --------------------------------------------------- |
| 0    | Other                                | See Text field                                      |
| 1    | Unknown ID                           | Referenced ID not found                             |
| 2    | Unknown Security                     | Invalid symbol                                      |
| 3    | Unsupported Message Type             | Message type not implemented on this margin session |
| 4    | Application not available            | System temporarily unavailable                      |
| 5    | Conditionally required field missing | Context-specific field missing                      |

## Order-Specific Rejections

### Order Reject Reasons (103)

In ExecutionReport (35=8) with `ExecType=Rejected`:

| Code | Reason                           | Common Causes                             |
| ---- | -------------------------------- | ----------------------------------------- |
| 1    | Unknown symbol                   | Invalid margin market ticker              |
| 2    | Exchange closed                  | Trading paused or unavailable             |
| 3    | Order exceeds limit              | Risk limit breach or insufficient margin  |
| 4    | Too late to enter                | Market not accepting new orders           |
| 5    | Stale order                      | Expired timestamp on request              |
| 6    | Duplicate order                  | ClOrdID already used                      |
| 11   | Unsupported order characteristic | Invalid order parameters                  |
| 13   | Incorrect quantity               | Invalid order size                        |
| 15   | Unknown account                  | Subaccount not found or permission denied |
| 99   | Other                            | See Text field                            |

### Cancel Reject Reasons (102)

In OrderCancelReject (35=9):

| Code | Reason             | Description                                 |
| ---- | ------------------ | ------------------------------------------- |
| 0    | Too late to cancel | Order already filled                        |
| 1    | Unknown order      | Order not found or identifiers do not match |
| 99   | Other              | See Text field                              |

## Common Error Scenarios

**Example: Invalid Tag**

```fix theme={null}
// Sent
8=FIXT.1.1|35=D|11=123|38=10|333333=test|...

// Response: Reject
8=FIXT.1.1|35=3|45=5|58=Undefined tag received|371=333333|372=D|373=3|
```

**Example: Order Rejected by Exchange**

```fix theme={null}
// Sent
8=FIXT.1.1|35=D|11=456|38=10|55=BTC-PERP|44=19.5000|...

// Response: ExecutionReport (Rejected)
8=FIXT.1.1|35=8|11=456|150=8|39=8|58=EXCHANGE_PAUSED|103=2|...
```

<Note>
  Order-entry failures returned by the exchange are sent as ExecutionReport (35=8) with ExecType=Rejected, not as BusinessMessageReject. BusinessMessageReject (35=j) is used for application-layer failures before normal exchange rejection handling, such as rate limiting or listener-session restrictions.
</Note>

**Example: Insufficient Balance**

```fix theme={null}
// Response: ExecutionReport
8=FIXT.1.1|35=8|11=789|150=8|39=8|58=INSUFFICIENT_BALANCE|103=3|...
```

## Troubleshooting

### MsgSeqNum Too High on Logon

**Symptom**: Logon fails or the server sends a ResendRequest for messages the client doesn't have.

**Cause**: The client is sending a `MsgSeqNum` higher than what the server last saw. This typically happens when the client's local sequence store persists across sessions but the server has reset (e.g. after maintenance or a prior `ResetSeqNumFlag=Y` logon).

**Fix**:

* **KalshiNR, KalshiDC**: Set `ResetSeqNumFlag<141>=Y` on every Logon. These sessions require it; Logon will be rejected without it.
* **KalshiRT**: If you don't need to recover missed messages, set `ResetSeqNumFlag<141>=Y` to reset both sides to 1. If you do need retransmission continuity, ensure your local sequence store matches the server's state.

If using QuickFIX, set `ResetOnLogon=Y` in your session config for non-retransmission sessions.

### SendingTime Rejected

**Symptom**: Reject (35=3) with `SessionRejectReason<373>=10`.

**Cause**: The client's clock is more than 30 seconds off from the server. Sync your system clock via NTP.

### Duplicate Session ("already exists")

**Symptom**: Logout (35=5) immediately after Logon with `Text<58>="already exists"`.

**Cause**: Another FIX connection is already active with the same API key and TargetCompID. Only one connection is allowed per API key per session type. This can also occur if a previous connection was not cleanly closed and the server hasn't yet detected the disconnect.

**Fix**: Ensure the previous session is fully disconnected before reconnecting. If the prior connection was lost unexpectedly, wait for the server's heartbeat timeout to expire (up to 60 seconds depending on your `HeartbeatInt` setting) before retrying. Use separate API keys for concurrent connections.

### Logon Signature Rejected

**Symptom**: Logout immediately after Logon with a signature error.

**Cause**: The `SendingTime` used in the pre-hash string doesn't match the `SendingTime<52>` in the actual Logon message. If using a FIX library, the library may auto-populate `SendingTime`. Use that exact value when computing the signature, not a separately generated timestamp.