Explain how @Retry takes precedence over handlers

docs/source/user/quickstart.rst

@@ -558,6 +558,15 @@ Finally, like other Uplink decorators, you can decorate a :class:`Consumer`
 subclass with :class:`@retry <uplink.retry>` to :ref:`add retry support to all
 methods of that class <decorate_consumer>`.
 
+
+.. note::
+
+   Response and error handlers (see :ref:`here <custom response
+   handler>`) are invoked after the retry condition breaks or after all
+   retry attempts are exhausted, whatever comes first. These callbacks
+   will receive the first response/exception that triggers the retry's
+   ``stop`` condition or doesn't match its ``when`` filter.
+
 Client-Side Rate Limiting
 =========================
 

uplink/retry/retry.py

@@ -53,6 +53,21 @@ class retry(decorators.MethodAnnotation):
     which should benefit performance with remote services under high
     contention.
 
+    .. note::
+
+        Response and error handlers (see :ref:`here <custom response
+        handler>`) are invoked after the retry condition breaks or all
+        retry attempts are exhausted, whatever comes first. These
+        handlers will receive the first response/exception that triggers
+        the retry's ``stop`` condition or doesn't match its ``when``
+        filter.
+
+        In other words, responses or exceptions that match
+        the retry condition (e.g., retry when status code is 5xx) are
+        not subject to response or error handlers as long as the request
+        doesn't break the retry's stop condition (e.g., stop retrying
+        after 5 attempts).
+
     Args:
         when (optional): A predicate that determines when a retry
             should be attempted.