Document exceptions

components/promise.rst

@@ -74,5 +74,8 @@ executed if the request results in an error::
         }
     );
 
+The ``$exception`` of the failure callback SHOULD implement ``Http\Client\Exception``.
+See :doc:`../httplug/exceptions` for more information on the exception classes you might encounter.
+
 .. _`Promise PSR`: https://groups.google.com/forum/?fromgroups#!topic/php-fig/wzQWpLvNSjs
 .. _Promises/A+: https://promisesaplus.com

httplug/exceptions.rst

@@ -0,0 +1,26 @@
+Exceptions
+==========
+
+HTTPlug defines a common interface for all exceptions thrown by HTTPlug implementations.
+Every exception thrown by a HTTP client must implement ``Http\Client\Exception``.
+
+``HttpClient::sendRequest()`` can throw one of the following exceptions.
+
+================================== ============================= ===================
+Exception                          Thrown when                   Methods available
+================================== ============================= ===================
+TransferException                  something unexpected happened -
+└ RequestException                 the request is invalid        ``getRequest()``
+ |nbsp| |nbsp| └ NetworkException  no response received
+                                   due to network issues         ``getRequest()``
+ |nbsp| |nbsp| └ HttpException     error response                ``getRequest()``
+                                                                 ``getResponse()``
+================================== ============================= ===================
+
+.. note::
+
+    The ``sendAsyncRequest`` should never throw an exception but always return a
+    :doc:`../components/promise`. The exception classes used in ``Promise::wait`` and the ``then``
+    callback are however the same as explained here.
+
+.. |nbsp| unicode:: U+00A0 .. non-breaking space

httplug/introduction.rst

@@ -18,6 +18,7 @@ HTTPlug defines two HTTP client interfaces that we kept as simple as possible:
 
 * ``HttpAsyncClient`` defines a ``sendAsyncRequest`` method that sends a request
   asynchronously and always returns a ``Http\Client\Promise``.
+  See :doc:`../components/promise` for more information.
 
 Implementations
 ---------------

index.rst

@@ -65,6 +65,7 @@ for discussion around a future HTTP client PSR.
 
    Introduction <httplug/introduction>
    Usage <httplug/usage>
+   Exceptions <httplug/exceptions>
    Tutorial <httplug/tutorial>
    Migrating <httplug/migrating>