diff --git a/HACKING b/HACKING
index 8f990864c..bac532fe3 100644
--- a/HACKING
+++ b/HACKING
@@ -75,3 +75,9 @@ Docstrings
   :returns: description of the return value
 
   """
+
+Exceptions
+----------
+
+When dealing with exceptions from underlying libraries, translate those
+exceptions to an instance or subclass of ClientException.
diff --git a/doc/source/using-api.rst b/doc/source/using-api.rst
index b5d630c12..fb1aa3a23 100644
--- a/doc/source/using-api.rst
+++ b/doc/source/using-api.rst
@@ -29,6 +29,10 @@ You create a valid ``keystoneclient.v2_0.client.Client`` object by passing
 authentication data to the constructor. Authentication and examples of common
 tasks are provided below.
 
+You can generally expect that when the client needs to propogate an exception
+it will raise an instance of subclass of
+``keystoneclient.exceptions.ClientException``
+
 Authenticating
 ==============