Skip to content

Commit 9984a87

Browse files
authored
feat(core): add standard model exception types (#39538)
1 parent b3e9eef commit 9984a87

13 files changed

Lines changed: 726 additions & 19 deletions

File tree

‎libs/core/langchain_core/exceptions.py‎

Lines changed: 56 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,62 @@ def __init__(
6565
self.send_to_llm = send_to_llm
6666

6767

68-
class ContextOverflowError(LangChainException):
68+
class ModelError(LangChainException):
69+
"""Base exception for failures related to model invocation.
70+
71+
Subclasses correspond to conditions that model providers report consistently,
72+
keyed to the HTTP status they surface it with, so the same condition maps to
73+
the same exception type regardless of provider.
74+
75+
Provider integrations raise subclasses that also inherit from the provider
76+
SDK's own exception type, so code catching either continues to work.
77+
"""
78+
79+
is_retryable = False
80+
"""Whether retrying the same model request may succeed."""
81+
82+
83+
class ModelAuthenticationError(ModelError):
84+
"""Exception raised when model provider authentication fails (HTTP 401)."""
85+
86+
87+
class ModelPermissionDeniedError(ModelError):
88+
"""Exception raised when credentials lack permission for a request (HTTP 403)."""
89+
90+
91+
class ModelInvalidRequestError(ModelError):
92+
"""Exception raised when a provider rejects a request as invalid (e.g. HTTP 400)."""
93+
94+
95+
class ModelNotFoundError(ModelError):
96+
"""Exception raised when the requested model cannot be found (HTTP 404)."""
97+
98+
99+
class ModelRateLimitError(ModelError):
100+
"""Exception raised when a model provider rate limit is exceeded (HTTP 429)."""
101+
102+
is_retryable = True
103+
104+
105+
class ModelAPIError(ModelError):
106+
"""Exception raised when a model provider reports a server failure (HTTP 5xx)."""
107+
108+
is_retryable = True
109+
110+
111+
class ModelConnectionError(ModelError):
112+
"""Exception raised when a model provider cannot be reached."""
113+
114+
is_retryable = True
115+
116+
117+
class ModelTimeoutError(ModelError):
118+
"""Exception raised when a model request times out."""
119+
120+
is_retryable = True
121+
122+
123+
class ContextOverflowError(ModelError):
69124
"""Exception raised when input exceeds the model's context limit.
70125
71126
This exception is raised by chat models when the input tokens exceed

‎libs/langchain_v1/langchain/agents/middleware/_retry.py‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@
1010
from collections.abc import Callable
1111
from typing import Literal
1212

13+
from langchain_core.exceptions import ModelError
14+
1315
# Type aliases
1416
RetryOn = tuple[type[Exception], ...] | Callable[[Exception], bool]
1517
"""Type for specifying which exceptions to retry on.
@@ -65,6 +67,13 @@ def validate_retry_params(
6567
raise ValueError(msg)
6668

6769

70+
def default_retry_on(exc: Exception) -> bool:
71+
"""Return whether an exception should be retried by default."""
72+
if isinstance(exc, ModelError):
73+
return exc.is_retryable
74+
return True
75+
76+
6877
def should_retry_exception(
6978
exc: Exception,
7079
retry_on: RetryOn,

‎libs/langchain_v1/langchain/agents/middleware/model_retry.py‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@
1313
OnFailure,
1414
RetryOn,
1515
calculate_delay,
16+
default_retry_on,
1617
should_retry_exception,
1718
validate_retry_params,
1819
)
@@ -116,7 +117,7 @@ def __init__(
116117
self,
117118
*,
118119
max_retries: int = 2,
119-
retry_on: RetryOn = (Exception,),
120+
retry_on: RetryOn = default_retry_on,
120121
on_failure: OnFailure = "continue",
121122
backoff_factor: float = 2.0,
122123
initial_delay: float = 1.0,
@@ -132,8 +133,9 @@ def __init__(
132133
retry_on: Either a tuple of exception types to retry on, or a callable
133134
that takes an exception and returns `True` if it should be retried.
134135
135-
Default is to retry on all exceptions. Exceptions that do not match
136-
propagate immediately and are not handled by `on_failure`.
136+
By default, retryable model errors and all unclassified exceptions are
137+
retried. Exceptions that do not match propagate immediately and are not
138+
handled by `on_failure`.
137139
on_failure: Behavior when all retries are exhausted.
138140
139141
Options:

‎libs/langchain_v1/langchain/agents/middleware/tool_retry.py‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@
1414
OnFailure,
1515
RetryOn,
1616
calculate_delay,
17+
default_retry_on,
1718
should_retry_exception,
1819
validate_retry_params,
1920
)
@@ -134,7 +135,7 @@ def __init__(
134135
*,
135136
max_retries: int = 2,
136137
tools: list[BaseTool | str] | None = None,
137-
retry_on: RetryOn = (Exception,),
138+
retry_on: RetryOn = default_retry_on,
138139
on_failure: OnFailure = "continue",
139140
backoff_factor: float = 2.0,
140141
initial_delay: float = 1.0,
@@ -155,8 +156,9 @@ def __init__(
155156
retry_on: Either a tuple of exception types to retry on, or a callable
156157
that takes an exception and returns `True` if it should be retried.
157158
158-
Default is to retry on all exceptions. Exceptions that do not match
159-
propagate immediately and are not handled by `on_failure`.
159+
By default, retryable model errors and all unclassified exceptions are
160+
retried. Exceptions that do not match propagate immediately and are not
161+
handled by `on_failure`.
160162
on_failure: Behavior when all retries are exhausted.
161163
162164
Options:

‎libs/langchain_v1/tests/unit_tests/agents/middleware/implementations/test_model_retry.py‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,10 @@
66

77
import pytest
88
from langchain_core.callbacks import CallbackManagerForLLMRun
9+
from langchain_core.exceptions import (
10+
ModelAuthenticationError,
11+
ModelRateLimitError,
12+
)
913
from langchain_core.messages import AIMessage, BaseMessage, HumanMessage
1014
from langchain_core.outputs import ChatGeneration, ChatResult
1115
from langgraph.checkpoint.memory import InMemorySaver
@@ -68,6 +72,7 @@ class AlwaysFailingModel(FakeToolCallingModel):
6872

6973
error_message: str = Field(default="Model error")
7074
error_type: type[Exception] = Field(default=ValueError)
75+
attempts: int = Field(default=0)
7176

7277
@override
7378
def _generate(
@@ -88,6 +93,7 @@ def _generate(
8893
Raises:
8994
Exception: Always raises the configured exception.
9095
"""
96+
self.attempts += 1
9197
raise self.error_type(self.error_message)
9298

9399

@@ -321,6 +327,67 @@ def test_model_retry_non_retryable_exception_reraises() -> None:
321327
)
322328

323329

330+
@pytest.mark.parametrize(
331+
"error_type",
332+
[
333+
# Retryable model errors use the full retry budget.
334+
ModelRateLimitError,
335+
# Exceptions the taxonomy does not classify keep retrying as before.
336+
ValueError,
337+
],
338+
)
339+
def test_model_retry_retries_retryable_errors(error_type: type[Exception]) -> None:
340+
"""The default `retry_on` retries anything not marked non-retryable."""
341+
model = AlwaysFailingModel(error_message="boom", error_type=error_type)
342+
retry = ModelRetryMiddleware(
343+
max_retries=2,
344+
initial_delay=0,
345+
jitter=False,
346+
on_failure="continue",
347+
)
348+
agent = create_agent(
349+
model=model,
350+
tools=[],
351+
middleware=[retry],
352+
checkpointer=InMemorySaver(),
353+
)
354+
355+
result = agent.invoke(
356+
{"messages": [HumanMessage("Hello")]},
357+
{"configurable": {"thread_id": "test"}},
358+
)
359+
360+
assert model.attempts == 3
361+
ai_messages = [m for m in result["messages"] if isinstance(m, AIMessage)]
362+
assert "3 attempts" in ai_messages[-1].content
363+
364+
365+
def test_model_retry_reraises_non_retryable_model_error() -> None:
366+
"""Model errors marked non-retryable fail on the first attempt."""
367+
model = AlwaysFailingModel(error_message="boom", error_type=ModelAuthenticationError)
368+
retry = ModelRetryMiddleware(
369+
max_retries=2,
370+
initial_delay=0,
371+
jitter=False,
372+
on_failure="continue",
373+
)
374+
agent = create_agent(
375+
model=model,
376+
tools=[],
377+
middleware=[retry],
378+
checkpointer=InMemorySaver(),
379+
)
380+
381+
# Unmatched exceptions propagate without going through `on_failure`.
382+
with pytest.raises(ModelAuthenticationError):
383+
agent.invoke(
384+
{"messages": [HumanMessage("Hello")]},
385+
{"configurable": {"thread_id": "test"}},
386+
)
387+
388+
assert model.attempts == 1
389+
390+
324391
def test_model_retry_custom_exception_filter() -> None:
325392
"""Test ModelRetryMiddleware with custom exception filter function."""
326393

‎libs/partners/anthropic/langchain_anthropic/chat_models.py‎

Lines changed: 96 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,18 @@
1818
AsyncCallbackManagerForLLMRun,
1919
CallbackManagerForLLMRun,
2020
)
21-
from langchain_core.exceptions import ContextOverflowError, OutputParserException
21+
from langchain_core.exceptions import (
22+
ContextOverflowError,
23+
ModelAPIError,
24+
ModelAuthenticationError,
25+
ModelConnectionError,
26+
ModelInvalidRequestError,
27+
ModelNotFoundError,
28+
ModelPermissionDeniedError,
29+
ModelRateLimitError,
30+
ModelTimeoutError,
31+
OutputParserException,
32+
)
2233
from langchain_core.language_models import (
2334
LanguageModelInput,
2435
ModelProfile,
@@ -910,6 +921,46 @@ class AnthropicContextOverflowError(anthropic.BadRequestError, ContextOverflowEr
910921
"""BadRequestError raised when input exceeds Anthropic's context limit."""
911922

912923

924+
class AnthropicAuthenticationError(
925+
anthropic.AuthenticationError, ModelAuthenticationError
926+
):
927+
"""Anthropic authentication error classified as a LangChain model error."""
928+
929+
930+
class AnthropicPermissionDeniedError(
931+
anthropic.PermissionDeniedError, ModelPermissionDeniedError
932+
):
933+
"""Anthropic permission error classified as a LangChain model error."""
934+
935+
936+
class AnthropicInvalidRequestError(anthropic.BadRequestError, ModelInvalidRequestError):
937+
"""Anthropic bad-request error classified as a LangChain model error."""
938+
939+
940+
class AnthropicModelNotFoundError(anthropic.NotFoundError, ModelNotFoundError):
941+
"""Anthropic not-found error classified as a LangChain model error."""
942+
943+
944+
class AnthropicRateLimitError(anthropic.RateLimitError, ModelRateLimitError):
945+
"""Anthropic rate-limit error classified as a LangChain model error."""
946+
947+
948+
class AnthropicAPIError(anthropic.InternalServerError, ModelAPIError):
949+
"""Anthropic server error classified as a LangChain model error."""
950+
951+
952+
class AnthropicOverloadedError(anthropic.OverloadedError, ModelAPIError):
953+
"""Anthropic overloaded error (HTTP 529) classified as a LangChain model error."""
954+
955+
956+
class AnthropicConnectionError(anthropic.APIConnectionError, ModelConnectionError):
957+
"""Anthropic connection error classified as a LangChain model error."""
958+
959+
960+
class AnthropicTimeoutError(anthropic.APITimeoutError, ModelTimeoutError):
961+
"""Anthropic timeout error classified as a LangChain model error."""
962+
963+
913964
def _raise_if_authentication_error(e: TypeError) -> None:
914965
"""Re-raise anthropic SDK's missing-credentials `TypeError` with guidance."""
915966
if "Could not resolve authentication method" in str(e):
@@ -933,7 +984,42 @@ def _handle_anthropic_bad_request(e: anthropic.BadRequestError) -> None:
933984
if ("messages: at least one message is required") in e.message:
934985
message = "Received only system message(s). "
935986
warnings.warn(message, stacklevel=2)
936-
raise e
987+
raise AnthropicInvalidRequestError(
988+
message=e.message, response=e.response, body=e.body
989+
) from e
990+
991+
992+
def _handle_anthropic_api_error(e: anthropic.APIError) -> None:
993+
"""Re-raise an Anthropic SDK error as its LangChain-classified equivalent."""
994+
if isinstance(e, anthropic.AuthenticationError):
995+
raise AnthropicAuthenticationError(
996+
message=e.message, response=e.response, body=e.body
997+
) from e
998+
if isinstance(e, anthropic.PermissionDeniedError):
999+
raise AnthropicPermissionDeniedError(
1000+
message=e.message, response=e.response, body=e.body
1001+
) from e
1002+
if isinstance(e, anthropic.NotFoundError):
1003+
raise AnthropicModelNotFoundError(
1004+
message=e.message, response=e.response, body=e.body
1005+
) from e
1006+
if isinstance(e, anthropic.RateLimitError):
1007+
raise AnthropicRateLimitError(
1008+
message=e.message, response=e.response, body=e.body
1009+
) from e
1010+
if isinstance(e, anthropic.OverloadedError):
1011+
raise AnthropicOverloadedError(
1012+
message=e.message, response=e.response, body=e.body
1013+
) from e
1014+
if isinstance(e, anthropic.InternalServerError):
1015+
raise AnthropicAPIError(
1016+
message=e.message, response=e.response, body=e.body
1017+
) from e
1018+
# `APITimeoutError` subclasses `APIConnectionError`, so check it first.
1019+
if isinstance(e, anthropic.APITimeoutError):
1020+
raise AnthropicTimeoutError(e.request) from e
1021+
if isinstance(e, anthropic.APIConnectionError):
1022+
raise AnthropicConnectionError(message=e.message, request=e.request) from e
9371023
raise
9381024

9391025

@@ -1681,6 +1767,8 @@ def _stream(
16811767
yield chunk
16821768
except anthropic.BadRequestError as e:
16831769
_handle_anthropic_bad_request(e)
1770+
except anthropic.APIError as e:
1771+
_handle_anthropic_api_error(e)
16841772

16851773
async def _astream(
16861774
self,
@@ -1718,6 +1806,8 @@ async def _astream(
17181806
yield chunk
17191807
except anthropic.BadRequestError as e:
17201808
_handle_anthropic_bad_request(e)
1809+
except anthropic.APIError as e:
1810+
_handle_anthropic_api_error(e)
17211811

17221812
def _make_message_chunk_from_anthropic_event(
17231813
self,
@@ -2011,6 +2101,8 @@ def _generate(
20112101
data = self._create(payload)
20122102
except anthropic.BadRequestError as e:
20132103
_handle_anthropic_bad_request(e)
2104+
except anthropic.APIError as e:
2105+
_handle_anthropic_api_error(e)
20142106
return self._format_output(data, **kwargs)
20152107

20162108
async def _agenerate(
@@ -2025,6 +2117,8 @@ async def _agenerate(
20252117
data = await self._acreate(payload)
20262118
except anthropic.BadRequestError as e:
20272119
_handle_anthropic_bad_request(e)
2120+
except anthropic.APIError as e:
2121+
_handle_anthropic_api_error(e)
20282122
return self._format_output(data, **kwargs)
20292123

20302124
def _get_llm_for_structured_output_when_thinking_is_enabled(

0 commit comments

Comments
 (0)