doc(API): Document new error handler precedence logic

Question: should this be highlighted as a breaking change in the docs
somewhere? Perhaps that depends on which milestone it gets added in.
But it seems like maybe a NOTE box in the docs highlighting that
this is a breaking change for version X

falcon/api.py

@@ -533,6 +533,31 @@ def add_error_handler(self, exception, handler=None):
         the client.  Alternatively, a handler may modify `resp`
         directly.
 
+        An error handler "matches" a raised exception if the exception is an
+        instance of the corresponding exception type. If more than one error
+        handler matches the raised exception, the framework will choose the
+        most specific one. If multiple error handlers are registered for the
+        *same* exception class, then the most recently-registered handler is
+        used. For example, suppose we register error handlers as follows::
+
+            app = falcon.API()
+            app.add_error_handler(falcon.HTTPNotFound, custom_handle_not_found)
+            app.add_error_handler(falcon.HTTPError, custom_handle_http_error)
+            app.add_error_handler(Exception, custom_handle_uncaught_exception)
+            app.add_error_handler(falcon.HTTPNotFound, custom_handle_404)
+
+        QUESTION(csojinb): Do we want the usages of falcon.HTTP* below to include links to the error classes?
+
+        If an instance of ``falcon.HTTPForbidden`` is raised, it will be
+        handled by ``custom_handle_http_error``. ``falcon.HTTPError`` is a
+        superclass of ``falcon.HTTPForbidden`` and a subclass of ``Exception``,
+        so it is the most specific exception type with a registered handler.
+
+        If an instance of ``falcon.HTTPNotFound`` is raised, it will be handled
+        by ``custom_handle_404``, not by ``custom_handle_not_found``, because
+        ``custom_handle_404`` was registered more recently.
+
+
         Error handlers are matched in LIFO order. In other words, when
         searching for an error handler to match a raised exception, and
         more than one handler matches the exception type, the framework