Diagnosing Issues and Troubleshooting with the TWS API

It is important to remember that the TWS API is an interface or an extension of TWS and IB Gateway. When troubleshooting issues with the Excel samples or other API applications, it is important to check the corresponding TWS functions. The TWS can be used as a reference for the expected behavior of the API application, or to check if a legitimate issue stems from the TWS itself.  Additionally, when working with API applications, it is important to monitor error messages and gather diagnostics files and logs. These topics will all be covered in this video.

Example Case

Say you are requesting:

• Historical data via the Excel DDE sample.
• In row 12, we are requesting historical 1 day bars for IBKR.
• The endDateTime is 20200909 23:59:59.

With these parameters, you may assume that the last daily bar returned would have a time stamp of 20200907.

However, the timestamp of the last bar is “20200904”.To check why the response is not what’s expected, we can review the corresponding TWS function. In this case, the API historical bars function corresponds to TWS bar charts.

In our shifted graph, locate the bar with date 202009. Then, let’s count 3 day bars going back starting with 20200909.
In a TWS chart, if we try to count 3 bars at this date, the last bar is also 20200904 and there is no bar for 0907.

You have now confirmed the TWS shows the same results. To take it a step further and see if this is expected TWS behavior, you could check the IBKR trading schedule and found that trading was closed on 0907.

Error messages and Notifications

When an API function does not produce the expected results, the first thing to check for are error messages. Whenever a request is made to TWS by the API, some sort of response is usually expected, whether it is account management, market data, or an error message. Although there can be an issue that causes the TWS to never return a response to the API, it is fairly uncommon.

The API returns error messages via the error callback function. As with most callback functions, each message has a “reqId” or request Id associated with it. This ID will allow you to associate the error with a specific request, whether it be a placed order, a request for market data, etc.

Let’s go back to our first scenario where we were requesting historical data for IBKR via the DDE sample.
Now, let’s intentionally send an incorrect request.

• Here we will add an “R” to the end of the symbol to make the symbol invalid.
• No new output page was created, and if we scroll to column Z, there is an error.
• The error code is 200.
• This error indicates there is something wrong with our contract, in this case the symbol.
• An ID number associated with this historical data request and error is listed in column X.
• To see a list of most error messages and a description of what they indicate, go to the errors documentation page in Github.
• As a final note, when moving on to build custom API spreadsheets and applications, error messages will be essential as well in order to create a robust program that can respond to different situations.
• See our documentation on “Considerations for Automated Systems” for further information.

Log files and Diagnostics

• If you are not able to find the source of an issue by checking the TWS or reviewing the received error messages, the next step is to gather log files and diagnostics for review. Advanced logging must enabled in the API settings.
• Go to File, Global Configuration,API, Settings.
• Check the box “create API message log file.” This will create a separate log file, only recording API messages.
• Then, set the logging level to “Detail.” This will allow the TWS to record detailed API messages in its logs.
• Also, you may check the box “Include market data in API log file” if you are troubleshooting issues involving market
  data figures.

Now let’s click on Apply and Ok, and advanced API logging is enabled from this point forward.

After an issue occurs, the log files can be reviewed by either the client or an API support representative.

• A client may view their logs by going to the menu Account, Diagnostics, then choose either the TWS logs or the API logs.
• Choose a date and export the logs to a directory. Logs are saved as text files.
• To upload logs for review with an IBKR client services representative, press the keyboard combination Ctrl-Alt-Q in TWS or IB Gateway, or go to the Help menu and Upload Diagnostics.
• Then in the Upload Diagnostics window, press Submit.
• The TWS and API logs can be a bit complex, especially the TWS logs.

However, an important concept in the API logs is that a left arrow indicates an outbound message or request being sent from the API to TWS, and a right arrow is a message being returned by TWS to the API.

This covers the major concepts of issue diagnosing and troubleshooting. IBKR support representatives can help with further questions.
Please note that the API can help troubleshoot issues and review log files, however it cannot provide programming assistance or troubleshoot local operating system issues.

The topics discussed here are also documented in our API support page.

Additional Links

Troubleshooting and Support

Error Handling

Contact Us