Retries and redispatches

The retry and redispatch options attempt to reconnect after a failed connection or resend after a failed HTTP request, which can protect against the following faults:

• network connectivity issues (including SSL handshake errors and unexpected server failures)
• HTTP errors
• servers taking too long to respond

First, consider the behavior of health checks, which monitor each backend server’s connectivity and remove problematic servers from the load balancing rotation. After removing a server from load balancing, the flow of traffic is stopped to that server, which is preferable when the connectivity problem is likely to be long-lasting.

Nevertheless, not all connection problems are long lasting and retrying the connection immediately could successfully overcome short-term connection problems. Connection retries are enabled by default, but you can change their behavior.

Set the number of retries Jump to heading #

By default, the load balancer will retry a failed connection 3 times. To change the ultimate number of times the load balancer will try to reconnect:

1. In a defaults or backend section, add a retries directive and set its value to the number of times to retry a failed connection attempt.

   Below, we attempt to connect to the server 4 times before giving up and returning a Service Unavailable error to the client:

   haproxy
   backend webservers
     mode http
     balance roundrobin
     server s1 192.168.1.25:80 check
     server s2 192.168.1.26:80 check
     retries 4

   haproxy
   backend webservers
     mode http
     balance roundrobin
     server s1 192.168.1.25:80 check
     server s2 192.168.1.26:80 check
     retries 4

2. Optional: Add the timeout connect directive to set the delay between retries.

   Below, the server performs the next retry after 3 seconds, optimistically giving the server time to overcome from short-term connectivity issues.

   haproxy
   backend webservers
     mode http
     balance roundrobin
     server s1 192.168.1.25:80 check
     server s2 192.168.1.26:80 check
     retries 4
     timeout connect 3s

   haproxy
   backend webservers
     mode http
     balance roundrobin
     server s1 192.168.1.25:80 check
     server s2 192.168.1.26:80 check
     retries 4
     timeout connect 3s

Redispatch to a different server Jump to heading #

Instead of trying to reconnect to the same server, you can configure option redispatch to try with a different server in the backend.

1. Add the option redispatch directive to retry with a different server:

   haproxy
   backend webservers
     mode http
     balance roundrobin
     server s1 192.168.1.25:80 check
     server s2 192.168.1.26:80 check
     retries 4
     option redispatch

   haproxy
   backend webservers
     mode http
     balance roundrobin
     server s1 192.168.1.25:80 check
     server s2 192.168.1.26:80 check
     retries 4
     option redispatch

2. Optional: Add a number of times to retry with the same server before redispatching to a different server. Below, we dispatch the request to another server after 2 failed retries:

   haproxy
   backend webservers
     mode http
     balance roundrobin
     server s1 192.168.1.25:80 check
     server s2 192.168.1.26:80 check
     retries 4
     option redispatch 2

   haproxy
   backend webservers
     mode http
     balance roundrobin
     server s1 192.168.1.25:80 check
     server s2 192.168.1.26:80 check
     retries 4
     option redispatch 2

Set when to retry Jump to heading #

Beyond retrying after a failed connection, you can also enable other conditions that should trigger a retry. Use the retry-on directive to specify the conditions.

1. Add the retry-on directive to define types of HTTP response codes that should trigger a retry. Below, we retry when the request fails due to failure 503 Service Unavailable or 504 Gateway Timeout:

   haproxy
   backend webservers
     mode http
     balance roundrobin
     server s1 192.168.1.25:80 check
     server s2 192.168.1.26:80 check
     retries 4
     retry-on 503 504

   haproxy
   backend webservers
     mode http
     balance roundrobin
     server s1 192.168.1.25:80 check
     server s2 192.168.1.26:80 check
     retries 4
     retry-on 503 504

   Options for the codes are:

   • 404
   • 408
   • 425
   • 500
   • 501
   • 502
   • 503
   • 504

   If you set retry-on, the default behavior of retrying failed TCP connections is not enabled unless you set retry-on to all-retryable-errors or a specific connection failure condition, such as conn-failure.

2. Optional: Add to the retry-on directive specific types of TCP connection problems that should also trigger a retry, in addition to HTTP response codes. Options include:

   • conn-failure
   • empty-response
   • junk-response
   • response-timeout
   • 0rtt-rejected
   • all-retryable-errors

   Below, we retry the connection if the connection could not be established or was closed while sending the request, in addition to when receiving a 503 response:

   haproxy
   backend webservers
     retry-on conn-failure empty-response 503

   haproxy
   backend webservers
     retry-on conn-failure empty-response 503

See also Jump to heading #

• option redispatch
• retries
• retry-on
• timeout connect