TWS error 502: cannot connect to the API

Quick answer

Error 502 means the app could not open its connection to TWS or IB Gateway. Start with the running program, host, and port. This is usually a connection setup problem, before an order reaches the broker.

Educational software guidance. Trading involves risk. Read the financial and information disclaimers.

Step by step

1 Check that TWS has finished logging in. A login screen is not a ready API session.
2 Open Global Configuration → API → Settings. Confirm socket clients are enabled and write down Socket port.
3 Compare the app host with the machine running TWS. Use 127.0.0.1 only when both apps run on the same machine.
4 Match the port exactly. TWS paper commonly uses 7497; Gateway paper commonly uses 4002. Custom ports are possible.
5 Reconnect once. If it still fails, check the app connection log and the local firewall rule for this specific connection.

A practical example

Suppose TWS shows port 7497 but the app tries 4002. The app is knocking at the wrong door. Change the app’s port to the value you read in TWS, then try to connect once. If the app is on a second computer, check the host too. The number 127.0.0.1 means this computer. It does not mean the other computer where you left TWS open.

Illustrative scenario, not a record of a trade placed during this review.

Screen reference

Start in Mosaic with File → Global Configuration. Then choose the panel named in the steps.

TWS API Settings showing socket clients, read-only access, port and logging — Find the named control in API → Settings. The displayed values belong to a paper session and are examples, not universal recommendations. Captured in TWS paper mode on 3 October 2026. Open the image for full size.

How to confirm the result The connection should progress to account discovery. If the same 502 remains, send support the host, port, app names, and time of the attempt.

Mistake to avoid

Repeatedly changing order permissions will not fix a socket that cannot open. Error 502 may not appear in TWS logs because the operating system reports it.

Common questions

Is 502 an order rejection?

No. It concerns the connection, before normal order processing.

Should I disable my firewall?

Use a narrow rule for the needed connection. Do not turn off the whole firewall.

How to enable the TWS API for PickMyTrade TWS and IB Gateway ports: paper versus live TWS connects but orders fail: check Read-Only API TWS error 507 or EOF: the API socket closed

Financial and information disclaimers

Financial disclaimer

These guides explain software. They are for education, not financial, investment, tax, or legal advice. No example is a suggestion to buy or sell a product or use a trading strategy. Trading can lose money, including all funds you put at risk. With margin, futures, short sales, or some options, losses can exceed your starting funds. Automation can fail, send duplicate orders, or act late. Stops do not guarantee a fill or a price. Review your orders and positions, and seek advice from a qualified professional for your own needs. Paper trades, examples, and past results do not predict live results or promise a profit.

Information disclaimer

This is general help based on the sources and check date shown on the page. Screens, settings, fees, data access, and product support can change or differ by app version, account, country, and broker. The content may contain errors or become out of date; accuracy, completeness, and continuous service are not guaranteed. Check current broker and app instructions before acting. Screenshots show where controls are; they do not prove that an order test passed. This guide does not replace broker terms or risk notices. References to IBKR and TradingView identify their products and do not imply their endorsement of this guide.