Claus Ibsen created CAMEL-24550:
-----------------------------------
Summary: Document how to target OpenAI/LangChain4j/Spring AI
component exceptions with onException for rate-limit and retry handling
Key: CAMEL-24550
URL: https://issues.apache.org/jira/browse/CAMEL-24550
Project: Camel
Issue Type: Improvement
Components: camel-openai
Reporter: Claus Ibsen
The camel-openai producer (and the equivalent
camel-langchain4j-chat/-agent/-embeddings and camel-spring-ai-chat producers)
do not wrap or reclassify exceptions thrown by the underlying SDK — they
propagate the SDK's own typed exceptions unchanged (e.g. openai-java's
com.openai.errors.RateLimitException, InternalServerException,
UnprocessableEntityException, BadRequestException, etc.).
This means route authors can already write targeted error handling today, e.g.:
{code:java}
onException(RateLimitException.class)
.maximumRedeliveries(5)
.redeliveryDelay(2000)
.backOffMultiplier(2)
.end();
{code}
vs. failing fast on a non-retryable error such as a context-length/validation
error (e.g. UnprocessableEntityException/BadRequestException), which should NOT
be retried.
However, none of this is documented. The component docs (openai-component.adoc)
only say generically that "API-specific exceptions from the OpenAI SDK for
network errors, authentication failures, rate limiting, etc." propagate as-is,
without telling users the exception types are distinguishable or giving an
example of onException usage for retryable vs. non-retryable AI errors.
Proposed fix: add a documentation section (and equivalent for
langchain4j/spring-ai component docs where their own SDKs expose similarly
typed exceptions) showing:
- The relevant typed exception classes users can catch.
- A recommended onException pattern distinguishing retryable (rate limit/5xx)
vs. terminal (validation/auth/context-length) errors.
- A note on the interaction with the SDK's own built-in retry (maxRetries URI
option) vs. Camel-level redelivery, so users don't double-retry unintentionally.
This is a documentation-only change with no code/API impact.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
