Document on_error "special" behavior

docs/api.rst

@@ -195,6 +195,14 @@ to handle it, which defaults to print a traceback and ignoring the exception.
     :ref:`py:raise`.  Exceptions raised by ``on_error`` will not be
     handled in any way by :class:`Client`.
 
+    .. note::
+
+        ``on_error`` will only be dispatched to :meth:`Client.event`.
+
+        It will not be received by :meth:`Client.wait_for`, or, if used,
+        :ref:`ext_commands_api_bot` listeners such as
+        :meth:`~ext.commands.Bot.listen` or :meth:`~ext.commands.Cog.listener`.
+
     :param event: The name of the event that raised the exception.
     :type event: :class:`str`