​
Error Handling

​
Overview

Kalshi FIX API 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 specific rejection messages

​
Error Message Types

​
Reject (35=3)

Used for session-level protocol violations.
TagNameDescriptionRequired
45RefSeqNumSequence number of rejected messageYes
58TextHuman-readable error descriptionNo
371RefTagIDTag that caused the rejectionNo
372RefMsgTypeMessage type being rejectedNo
373SessionRejectReasonRejection reason codeNo

​
Session Reject Reasons (373)

CodeReasonDescription
0Invalid tag numberUnknown tag in message
1Required tag missingMandatory field not present
2Tag not defined for messageTag not valid for this message type
3Undefined tagTag number not in FIX specification
4Tag without valueEmpty tag value
5Incorrect valueInvalid value for tag
6Incorrect data formatWrong data type
7Decryption problemSecurity issue
8Signature problemAuthentication failure
9CompID problemSenderCompID/TargetCompID issue
10SendingTime accuracyTime outside acceptable window
11Invalid MsgTypeUnknown message type

​
BusinessMessageReject (35=j)

Used for application-level business logic errors.
TagNameDescriptionRequired
45RefSeqNumSequence number of rejected messageYes
58TextHuman-readable error descriptionNo
371RefTagIDTag that caused the rejectionNo
372RefMsgTypeMessage type being rejectedNo
379BusinessRejectRefIDBusiness ID from rejected messageNo
380BusinessRejectReasonBusiness rejection reason codeYes

​
Business Reject Reasons (380)

CodeReasonDescription
0OtherSee Text field for details
1Unknown IDReferenced ID not found
2Unknown SecurityInvalid symbol
3Unsupported Message TypeMessage type not implemented
4Application not availableSystem temporarily unavailable
5Conditionally required field missingContext-specific field missing

​
Order-Specific Rejections

​
Order Reject Reasons (103)

In ExecutionReport (35=8) with ExecType=Rejected:
CodeReasonCommon Causes
1Unknown symbolInvalid market ticker
2Exchange closedOutside trading hours
3Order exceeds limitPosition or order size limit
4Too late to enterMarket expired/closed
6Duplicate orderClOrdID already used
11Unsupported order characteristicInvalid order parameters
99OtherSee Text field

​
Cancel Reject Reasons (102)

In OrderCancelReject (35=9):
CodeReasonDescription
0Too late to cancelOrder already filled
1Unknown orderOrder ID not found
99OtherSee Text field

​
Common Error Scenarios

​
Example 1: Invalid Tag

Scenario: Undefined tag in NewOrderSingle 
// 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 2: Business Logic Error

Scenario: Trading during maintenance 
// Sent
8=FIXT.1.1|35=D|11=456|38=10|55=HIGHNY-23DEC31|...

// Response: BusinessMessageReject
8=FIXT.1.1|35=j|45=10|58=Kalshi exchange unavailable|372=D|380=4|

​
Example 3: Order Rejection

Scenario: Insufficient funds 
// Response: ExecutionReport
8=FIXT.1.1|35=8|11=789|150=8|39=8|58=Insufficient funds|103=99|...

​
Error Handling Best Practices

​
1. Comprehensive Logging

def handle_message(msg):
    if msg.type == 'Reject':
        log.error(f"Session reject: {msg.Text} (Tag: {msg.RefTagID}, Reason: {msg.SessionRejectReason})")
    elif msg.type == 'BusinessMessageReject':
        log.error(f"Business reject: {msg.Text} (Reason: {msg.BusinessRejectReason})")
    elif msg.type == 'ExecutionReport' and msg.ExecType == 'Rejected':
        log.error(f"Order rejected: {msg.Text} (Reason: {msg.OrdRejReason})")

​
2. Retry Strategies

Error TypeRetry Strategy
Session errorsFix protocol issue before retry
Rate limitExponential backoff
Exchange closedWait for market open
Insufficient fundsCheck balance before retry
Unknown symbolVerify symbol, don’t retry

​
3. Graceful Degradation

1

Identify Error Type

Distinguish between recoverable and non-recoverable errors
2

Apply Appropriate Action

  • Recoverable: Implement retry with backoff
  • Non-recoverable: Alert and halt
3

Monitor and Alert

Track error rates and patterns for system health

​
Specific Error Conditions

​
Authentication Errors

SymptomLikely CauseResolution
Logon rejectedInvalid signatureCheck RSA key and signature algorithm
CompID problemWrong API keyVerify SenderCompID matches API key
Time accuracyClock skewSync system time with NTP

​
Order Entry Errors

ErrorCheckAction
Unknown symbolSymbol formatUse exact ticker from market data
Order exceeds limitPosition limitsQuery current position
Duplicate ClOrdIDID generationEnsure UUID uniqueness
Invalid pricePrice rangeEnsure 1-99 cents

​
Connection Errors

Connection errors often manifest as:
  • Heartbeat timeout
  • Sequence number gaps
  • Socket disconnection
Always implement reconnection logic with appropriate delays.

​
Error Response Patterns

​
Synchronous Errors

Immediate response to invalid request: 
Request → Validation → Immediate Error Response

​
Asynchronous Errors

Delayed errors during processing: 
Request → Initial Accept → Processing → Later Error Report