This is an automated email from the ASF dual-hosted git repository.
davsclaus pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel.git
The following commit(s) were added to refs/heads/main by this push:
new 3c4552bd6222 chore: clarify what handled(true) means in onException
docs
3c4552bd6222 is described below
commit 3c4552bd62224b97737044cdc1d22b0a5f3c260d
Author: Claus Ibsen <[email protected]>
AuthorDate: Tue Jun 23 14:30:41 2026 +0200
chore: clarify what handled(true) means in onException docs
Co-Authored-By: Claude Opus 4.6 <[email protected]>
---
.../user-manual/modules/ROOT/pages/exception-clause.adoc | 16 ++++++++++++++++
1 file changed, 16 insertions(+)
diff --git a/docs/user-manual/modules/ROOT/pages/exception-clause.adoc
b/docs/user-manual/modules/ROOT/pages/exception-clause.adoc
index 0a5d500e1c40..41c979e8ba26 100644
--- a/docs/user-manual/modules/ROOT/pages/exception-clause.adoc
+++ b/docs/user-manual/modules/ROOT/pages/exception-clause.adoc
@@ -498,6 +498,22 @@ what you want.
See also the section <<Handle and Continue Exceptions>> below.
+`handled(true)` tells Camel: _don't send the exception back to the caller —
I'll provide the
+response myself in this `onException` block, and then we're done._
+
+Three things to keep in mind:
+
+* *The original route stops* — the exchange does not continue from where it
failed in the main route.
+Only the steps in the `onException` block execute.
+* *The response is whatever the `onException` block produces* — use
`transform`, `bean`, or `to` to
+build the response you want the caller to receive. If you don't set a
response, the caller gets an
+empty body, not the exception.
+* *`exchange.getException()` is null* inside the `onException` block — use
+`exchange.getProperty(Exchange.EXCEPTION_CAUGHT, Exception.class)` to access
the original exception.
+
+This is different from `continued(true)`, which also suppresses the exception
but then *resumes the
+original route* from the point of failure as if the exception never happened.
+
Using *`onException`* to handle known exceptions is a very powerful
feature in Camel. You can mark the exception as being handled with the
*handle* DSL,
so the caller will not receive the caused exception as a response. The handle
is a
