+doc,htc #18600,18597 documents where/how to deal with failure in Http

akka-docs-dev/rst/scala/http/routing-dsl/directives/execution-directives/handleExceptions.rst

@@ -17,7 +17,7 @@ Description
 Using this directive is an alternative to using a global implicitly defined ``ExceptionHandler`` that
 applies to the complete route.
 
-See :ref:`Exception Handling` for general information about options for handling exceptions.
+See :ref:`exception-handling-scala` for general information about options for handling exceptions.
 
 Example
 -------

akka-docs-dev/rst/scala/http/routing-dsl/directives/route-directives/failWith.rst

@@ -4,7 +4,7 @@ failWith
 ========
 
 Bubbles up the given error through the route structure where it is dealt with by the closest ``handleExceptions``
-directive and its ``ExceptionHandler``.
+directive and its :class:`ExceptionHandler`.
 
 
 Signature
@@ -19,12 +19,12 @@ Description
 
 ``failWith`` explicitly raises an exception that gets bubbled up through the route structure to be picked up by the
 nearest ``handleExceptions`` directive. Using ``failWith`` rather than simply throwing an exception enables the route
-structure's :ref:`Exception Handling` mechanism to deal with the exception even if the current route is executed
+structure's :ref:`exception-handling-scala` mechanism to deal with the exception even if the current route is executed
 asynchronously on another thread (e.g. in a ``Future`` or separate actor).
 
 If no ``handleExceptions`` is present above the respective location in the
 route structure the top-level routing logic will handle the exception and translate it into a corresponding
-``HttpResponse`` using the in-scope ``ExceptionHandler`` (see also the :ref:`Exception Handling` chapter).
+``HttpResponse`` using the in-scope ``ExceptionHandler`` (see also the :ref:`exception-handling-scala` chapter).
 
 There is one notable special case: If the given exception is a ``RejectionError`` exception it is *not* bubbled up,
 but rather the wrapped exception is unpacked and "executed". This allows the "tunneling" of a rejection via an

akka-docs-dev/rst/scala/http/routing-dsl/exception-handling.rst

@@ -1,4 +1,4 @@
-.. _Exception Handling:
+.. _exception-handling-scala:
 
 Exception Handling
 ==================

akka-docs-dev/rst/scala/http/routing-dsl/index.rst

@@ -43,4 +43,34 @@ not really do anything useful but its definition should give you a feel for what
 the Routing DSL will look like:
 
 .. includecode2:: ../../code/docs/http/scaladsl/HttpServerExampleSpec.scala
-   :snippet: long-routing-example
+   :snippet: long-routing-example
+
+.. _handling-http-server-failures-high-level-scala:
+
+Handling HTTP Server failures in the High-Level API
+---------------------------------------------------
+There are various situations when failure may occur while initialising or running an Akka HTTP server.
+Akka by default will log all these failures, however sometimes one may want to react to failures in addition
+to them just being logged, for example by shutting down the actor system, or notifying some external monitoring
+end-point explicitly.
+
+Bind failures
+^^^^^^^^^^^^^
+For example the server might be unable to bind to the given port. For example when the port
+is already taken by another application, or if the port is privileged (i.e. only usable by ``root``).
+In this case the "binding future" will fail immediatly, and we can react to if by listening on the Future's completion:
+
+.. includecode2:: ../../code/docs/http/scaladsl/HttpServerExampleSpec.scala
+  :snippet: binding-failure-high-level-example
+
+
+.. note::
+  For a more low-level overview of the kinds of failures that can happen and also more fine-grained control over them
+  refer to the :ref:`handling-http-server-failures-low-level-scala` documentation.
+
+Failures and exceptions inside the Routing DSL
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Exception handling within the Routing DSL is done by providing :class:`ExceptionHandler` s which are documented in-depth
+in the :ref:`exception-handling-scala` section of the documtnation. You can use them to transform exceptions into
+:class:`HttpResponse` s with apropriate error codes and human-readable failure descriptions.

akka-docs-dev/rst/scala/http/routing-dsl/routes.rst

@@ -14,7 +14,7 @@ Generally when a route receives a request (or rather a ``RequestContext`` for it
 
 - Complete the request by returning the value of ``requestContext.complete(...)``
 - Reject the request by returning the value of ``requestContext.reject(...)`` (see :ref:`Rejections`)
-- Fail the request by returning the value of ``requestContext.fail(...)`` or by just throwing an exception (see :ref:`Exception Handling`)
+- Fail the request by returning the value of ``requestContext.fail(...)`` or by just throwing an exception (see :ref:`exception-handling-scala`)
 - Do any kind of asynchronous processing and instantly return a ``Future[RouteResult]`` to be eventually completed later
 
 The first case is pretty clear, by calling ``complete`` a given response is sent to the client as reaction to the