Add documentation for retry on idempotent methods

Author: jderusse

http_client.rst

@@ -694,9 +694,10 @@ Retry Failed Requests
 Sometimes, requests fail because of network issues or temporary server errors.
 Symfony's HttpClient allows to retry failed requests automatically using the
 :ref:`retry_failed option <reference-http-client-retry-failed>`. When enabled,
-each failed request with an HTTP status of ``423``, ``425``, ``429``, ``500``,
-``502``, ``503``, ``504``, ``507``, or ``510`` is retried up to 3 times, with an
-exponential delay between retries (first retry = 1 second; third retry: 4 seconds).
+each failed request with an HTTP status of ``423``, ``425``, ``429``, ``502``,
+``503`` or with an `idempotent method`_ and a HTTP status of ``500``, ``504``,
+``507`` or ``510`` is retried up to 3 times, with an exponential delay between
+retries (first retry = 1 second; third retry: 4 seconds).
 
 Check out the full list of configurable :ref:`retry_failed options <reference-http-client-retry-failed>`
 to learn how to tweak each of them to fit your application needs.
@@ -1610,3 +1611,4 @@ Then configure Symfony to use your callback:
 .. _`cURL options`: https://www.php.net/manual/en/function.curl-setopt.php
 .. _`Server-sent events`: https://html.spec.whatwg.org/multipage/server-sent-events.html
 .. _`EventSource`:  https://www.w3.org/TR/eventsource/#eventsource
+.. _`idempotent method`:  https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Idempotent_methods_and_web_applications

reference/configuration/framework.rst

@@ -782,7 +782,10 @@ will automatically retry failed HTTP requests.
             retry_failed:
                 # backoff_service: app.custom_backoff
                 # decider_service:  app.custom_decider
-                http_codes: [429, 500]
+                http_codes:
+                    0: ['GET', 'HEAD']   # Retries Network errors when request's method is GET or HEAD
+                    429: true            # Alway retries response with 429 status codes
+                    500: ['GET', 'HEAD']
                 max_retries: 2
                 delay: 1000
                 multiplier: 3
@@ -956,13 +959,16 @@ value must use the format ``['header-name' => 'value0, value1, ...']``.
 http_codes
 ..........
 
-**type**: ``array`` **default**: ``[423, 425, 429, 500, 502, 503, 504, 507, 510]``
+**type**: ``array`` **default**: empty
 
 .. versionadded:: 5.2
 
     The ``http_codes`` option was introduced in Symfony 5.2.
 
 The list of HTTP status codes that triggers a retry of the request.
+When an empty array is provided, the default values from
+:method:`Symfony\Component\HttpClient\Retry\GenericRetryStrategy::DEFAULT_RETRY_STATUS_CODES`.
+is used.
 
 http_version
 ............