1[[set-retries]]
2=== Set retries
3
4By default, the client will retry `n` times, where `n = number of nodes` in your
5cluster. A retry is only performed if the operation results in a "hard"
6exception: connection refusal, connection timeout, DNS lookup timeout, etc. 4xx
7and 5xx errors are not considered retriable events, since the node returns an
8operational response.
9
10If you would like to disable retries, or change the number, you can do so with
11the `setRetries()` method:
12
13[source,php]
14----------------------------
15
16$client = ClientBuilder::create()
17                    ->setRetries(2)
18                    ->build();
19----------------------------
20
21When the client runs out of retries, it will throw the last exception that it
22received. For example, if you have ten alive nodes, and `setRetries(5)`, the
23client attempts to execute the command up to five times. If all five nodes
24result in a connection timeout (for example), the client will throw an
25`OperationTimeoutException`. Depending on the Connection Pool being used, these
26nodes may also be marked dead.
27
28To help in identification, exceptions that are thrown due to max retries wrap a
29`MaxRetriesException`. For example, you can catch a specific curl exception then
30check if it wraps a MaxRetriesException using `getPrevious()`:
31
32[source,php]
33----
34$client = Elasticsearch\ClientBuilder::create()
35    ->setHosts(["localhost:1"])
36    ->setRetries(0)
37    ->build();
38
39try {
40    $client->search($searchParams);
41} catch (Elasticsearch\Common\Exceptions\Curl\CouldNotConnectToHost $e) {
42    $previous = $e->getPrevious();
43    if ($previous instanceof 'Elasticsearch\Common\Exceptions\MaxRetriesException') {
44        echo "Max retries!";
45    }
46}
47----
48
49Alternatively, all "hard" curl exceptions (`CouldNotConnectToHost`,
50`CouldNotResolveHostException`, `OperationTimeoutException`) extend the more
51general `TransportException`. So you could instead catch the general
52`TransportException` and then check it's previous value:
53
54[source,php]
55----
56$client = Elasticsearch\ClientBuilder::create()
57    ->setHosts(["localhost:1"])
58    ->setRetries(0)
59    ->build();
60
61try {
62    $client->search($searchParams);
63} catch (Elasticsearch\Common\Exceptions\TransportException $e) {
64    $previous = $e->getPrevious();
65    if ($previous instanceof 'Elasticsearch\Common\Exceptions\MaxRetriesException') {
66        echo "Max retries!";
67    }
68}
69----