Skip to main content

Simulate Connection Timeout Error

TCP connection timeout is like waiting for a friend's reply to your message, and if they don't respond after a certain time, you assume they are busy and stop trying to reach them.

Bugs resulting from connection timeouts in HTTP connections can indeed be challenging to reproduce or simulate. Such issues may arise when the application encounters a connection timeout, and these specific scenarios might not have been handled in the code before. Debugging such bugs can prove to be intricate. Below are some common issues that can occur in a software application when a connection to an API server times out:

  • Unresponsive Application: When an application relies on an APIs and a connection timeout occurs, the application may become unresponsive/freeze as it waits for the connection to be established or data to be fetched.
  • Data Loss: When transferring data over a network connection, if the connection times out during the transfer process, it can result in partial or complete data loss, leading to data integrity issues between client and a server application.
  • Stale Caches: Applications often use caching mechanisms to improve performance by storing previously fetched data. If a connection timeout occurs while updating cached data, it can lead to outdated or stale information being served to users. These are typically solved by asking to clear cache, however, the root cause somewhere is a software bug which should retry updating cache.
  • Resource Leaks: In some cases, when a connection timeout happens, resources like sockets or database connections might not be properly closed or released, leading to resource/memory leaks and potential performance issues over time.

TCP connection timeout humour comic strip

How hard is to simulate connection timeout?

TCP timeout in technical terms

In technical terms of Transmission Control Protocol (TCP), a connection timeout happens when a TCP connection attempt (from the client) expects the server to respond but the server didn't respond within the stipulated time. The connection attempt is deemed unsuccessful, and the connection is considered timed out throwing an exception on the client side.

The TCP connection establishment process involves a series of steps known as the "TCP three-way handshake." as described below:

Step 1 (Client to Server - SYN): The client initiates the connection by sending a TCP packet with the SYN (Synchronize) flag set to the server. This packet contains a randomly generated sequence number, indicating the client's initial sequence number.

Step 2 (Server to Client - SYN-ACK): Upon receiving the SYN packet from the client, the server responds by sending a TCP packet with both the SYN and ACK (Acknowledgment) flags set. This packet acknowledges the receipt of the client's SYN packet and also contains the server's initial sequence number (also randomly generated) along with the acknowledgment of the client's sequence number.

Step 3 (Client to Server - ACK): Finally, the client acknowledges the receipt of the server's SYN-ACK packet by sending an ACK packet with the ACK flag set. This packet completes the three-way handshake, and the connection is established.

TCP normal 3-way handshake

A normal connection between a user/client and a server. The three-way handshake is correctly performed. Refer Wikipedia for more details.

How to test timeouts?

Connection timeout

Connection timeout is the maximum time a system waits to establish a connection with another system. If the connection is not established within the given time, it is considered failed, often due to unavailability of the other system or network issues.

  1. Firewalled Server with Non-standard Port: Connect to a server that has a firewall configured and use a non-standard port (e.g., 9001, 81, etc.). The firewall will typically drop TCP SYN packets, and the client will never receive an acknowledgment, causing it to wait until the configured timeout.
  2. Connection to Non-routable IP Address: Attempt to connect to a non-routable IP address, such as Depending on the network type, your code will either wait for a given time or return an unreachable host error.

Response Timeout

Response timeout is the maximum time a system waits for a response from another system after sending a request. If the response is not received within this time, the request is considered failed, and the system might retry or handle the error accordingly. It helps prevent waiting indefinitely for responses that might never arrive.

Beeceptor helps you simulate response timeouts. By creating a mock rule with a 60-second delay, you can mimic scenarios where the API server takes longer to respond. This aligns well with standard client application timeout settings of 30 or 60 seconds, enabling comprehensive testing of timeout handling.

mock rule, adding delay in Beeceptor

You can simulate delays and timeouts in Beeceptor.

Further reading

  1. Artificially create a connection timeout error -
  2. Setting up default socket timeout in Android -
  3. Writing a Java unit-test to simulate connection timeout - - code example. Java throws the same exception for connect and read timeouts