add documentation

Author: gwauge

docs/source/index.rst

@@ -154,6 +154,67 @@ Python's standard `logging framework`_.
 
 .. _logging framework: https://docs.python.org/3/library/logging.html
 
+Errors
+------
+
+The ``s3fs`` library includes a built-in mechanism to automatically retry 
+operations when specific transient errors occur. You can customize this behavior 
+by adding specific exception types or defining complex logic via custom handlers.
+
+Default Retryable Errors
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default, ``s3fs`` will retry the following exception types:
+
+- ``socket.timeout``
+- ``HTTPClientError``
+- ``IncompleteRead``
+- ``FSTimeoutError``
+- ``ResponseParserError``
+- ``aiohttp.ClientPayloadError`` (if available)
+
+Registering Custom Error Types
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To include additional exception types in the default retry logic, use the 
+``add_retryable_error`` function. This is useful for simple type-based retries.
+
+.. code-block:: python
+
+    >>> class MyCustomError(Exception):
+            pass
+    >>> s3fs.add_retryable_error(MyCustomError)
+
+Implementing Custom Error Handlers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For more complex scenarios, such as retrying based on an error message rather than 
+just the type, you can register a custom error handler using ``set_custom_error_handler``.
+
+The handler should be a callable that accepts an exception instance and returns ``True`` 
+if the error should be retried, or ``False`` otherwise.
+
+.. code-block:: python
+
+    >>> def my_handler(e):
+            return isinstance(e, MyCustomError) and "some condition" in str(e)
+    >>> s3fs.set_custom_error_handler(my_handler)
+
+Handling AWS ClientErrors
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``s3fs`` provides specialized handling for ``botocore.exceptions.ClientError``. 
+While ``s3fs`` checks these against internal patterns (like throttling), 
+you can extend this behavior using a custom handler. Note that the internal 
+patterns will still be checked and handled before the custom handler.
+
+.. code-block:: python
+
+    >>> def another_handler(e):
+            return isinstance(e, ClientError) and "Throttling" in str(e)
+    >>> s3fs.set_custom_error_handler(another_handler)
+
+
 Credentials
 -----------
 

s3fs/core.py

@@ -112,7 +112,7 @@ def set_custom_error_handler(func):
     >>> set_custom_error_handler(my_handler)  # doctest: +SKIP
 
     >>> def another_handler(e):  # doctest: +SKIP
-    ...     return isinstance(e, ClientError) and "Throttling" in str(e)  # doctest: +SKIP
+    ...     return isinstance(e, ClientError) and "Throttling" in str(e)"  # doctest: +SKIP
     >>> set_custom_error_handler(another_handler)  # doctest: +SKIP
     """
     global CUSTOM_ERROR_HANDLER