Skip to content

The agent engineering platform.

feat(core): add standard model exception types (#39538)

ccurme9984a87fa5a6
diff --git a/libs/core/langchain_core/exceptions.py b/libs/core/langchain_core/exceptions.py
index f58754c9d5..7b7edadb8b 100644
--- a/libs/core/langchain_core/exceptions.py
+++ b/libs/core/langchain_core/exceptions.py
@@ -65,7 +65,62 @@ class OutputParserException(ValueError, LangChainException): # noqa: N818
self.send_to_llm = send_to_llm
-class ContextOverflowError(LangChainException):
+class ModelError(LangChainException):
+ """Base exception for failures related to model invocation.
+
+ Subclasses correspond to conditions that model providers report consistently,
+ keyed to the HTTP status they surface it with, so the same condition maps to
+ the same exception type regardless of provider.
+
+ Provider integrations raise subclasses that also inherit from the provider
+ SDK's own exception type, so code catching either continues to work.
+ """
+
+ is_retryable = False
+ """Whether retrying the same model request may succeed."""
+
+
+class ModelAuthenticationError(ModelError):
+ """Exception raised when model provider authentication fails (HTTP 401)."""
+
+
+class ModelPermissionDeniedError(ModelError):
+ """Exception raised when credentials lack permission for a request (HTTP 403)."""
+
+
+class ModelInvalidRequestError(ModelError):
+ """Exception raised when a provider rejects a request as invalid (e.g. HTTP 400)."""
+
+
+class ModelNotFoundError(ModelError):
+ """Exception raised when the requested model cannot be found (HTTP 404)."""
+
+
+class ModelRateLimitError(ModelError):
+ """Exception raised when a model provider rate limit is exceeded (HTTP 429)."""
+
+ is_retryable = True
+
+
+class ModelAPIError(ModelError):
+ """Exception raised when a model provider reports a server failure (HTTP 5xx)."""
+
+ is_retryable = True
+
+
+class ModelConnectionError(ModelError):
+ """Exception raised when a model provider cannot be reached."""
+
+ is_retryable = True
+
+
+class ModelTimeoutError(ModelError):
+ """Exception raised when a model request times out."""
+
+ is_retryable = True
+
+
+class ContextOverflowError(ModelError):
"""Exception raised when input exceeds the model's context limit.
This exception is raised by chat models when the input tokens exceed
diff --git a/libs/langchain_v1/langchain/agents/middleware/_retry.py b/libs/langchain_v1/langchain/agents/middleware/_retry.py
index 89665cc328..c384e929bd 100644
--- a/libs/langchain_v1/langchain/agents/middleware/_retry.py
+++ b/libs/langchain_v1/langchain/agents/middleware/_retry.py
@@ -10,6 +10,8 @@ import random
from collections.abc import Callable
from typing import Literal
+from langchain_core.exceptions import ModelError
+
# Type aliases
RetryOn = tuple[type[Exception], ...] | Callable[[Exception], bool]
"""Type for specifying which exceptions to retry on.
@@ -65,6 +67,13 @@ def validate_retry_params(
raise ValueError(msg)
+def default_retry_on(exc: Exception) -> bool:
+ """Return whether an exception should be retried by default."""
+ if isinstance(exc, ModelError):
+ return exc.is_retryable
+ return True
+
+
def should_retry_exception(
exc: Exception,
retry_on: RetryOn,
diff --git a/libs/langchain_v1/langchain/agents/middleware/model_retry.py b/libs/langchain_v1/langchain/agents/middleware/model_retry.py
index 710de470b9..91083c1ab1 100644
--- a/libs/langchain_v1/langchain/agents/middleware/model_retry.py
+++ b/libs/langchain_v1/langchain/agents/middleware/model_retry.py
@@ -13,6 +13,7 @@ from langchain.agents.middleware._retry import (
OnFailure,
RetryOn,
calculate_delay,
+ default_retry_on,
should_retry_exception,
validate_retry_params,
)
@@ -116,7 +117,7 @@ class ModelRetryMiddleware(AgentMiddleware[AgentState[ResponseT], ContextT, Resp
self,
*,
max_retries: int = 2,
- retry_on: RetryOn = (Exception,),
+ retry_on: RetryOn = default_retry_on,
on_failure: OnFailure = "continue",
backoff_factor: float = 2.0,
initial_delay: float = 1.0,
@@ -132,8 +133,9 @@ class ModelRetryMiddleware(AgentMiddleware[AgentState[ResponseT], ContextT, Resp
retry_on: Either a tuple of exception types to retry on, or a callable
that takes an exception and returns `True` if it should be retried.
- Default is to retry on all exceptions. Exceptions that do not match
- propagate immediately and are not handled by `on_failure`.
+ By default, retryable model errors and all unclassified exceptions are
+ retried. Exceptions that do not match propagate immediately and are not
+ handled by `on_failure`.
on_failure: Behavior when all retries are exhausted.
Options:
diff --git a/libs/langchain_v1/langchain/agents/middleware/tool_retry.py b/libs/langchain_v1/langchain/agents/middleware/tool_retry.py
index a00bc2fe97..437fd78eae 100644
--- a/libs/langchain_v1/langchain/agents/middleware/tool_retry.py
+++ b/libs/langchain_v1/langchain/agents/middleware/tool_retry.py
@@ -14,6 +14,7 @@ from langchain.agents.middleware._retry import (
OnFailure,
RetryOn,
calculate_delay,
+ default_retry_on,
should_retry_exception,
validate_retry_params,
)
@@ -134,7 +135,7 @@ class ToolRetryMiddleware(AgentMiddleware[AgentState[ResponseT], ContextT, Respo
*,
max_retries: int = 2,
tools: list[BaseTool | str] | None = None,
- retry_on: RetryOn = (Exception,),
+ retry_on: RetryOn = default_retry_on,
on_failure: OnFailure = "continue",
backoff_factor: float = 2.0,
initial_delay: float = 1.0,
@@ -155,8 +156,9 @@ class ToolRetryMiddleware(AgentMiddleware[AgentState[ResponseT], ContextT, Respo
retry_on: Either a tuple of exception types to retry on, or a callable
that takes an exception and returns `True` if it should be retried.
- Default is to retry on all exceptions. Exceptions that do not match
- propagate immediately and are not handled by `on_failure`.
+ By default, retryable model errors and all unclassified exceptions are
+ retried. Exceptions that do not match propagate immediately and are not
+ handled by `on_failure`.
on_failure: Behavior when all retries are exhausted.
Options:
diff --git a/libs/langchain_v1/tests/unit_tests/agents/middleware/implementations/test_model_retry.py b/libs/langchain_v1/tests/unit_tests/agents/middleware/implementations/test_model_retry.py
index 3a1a741d23..8f849ea05e 100644
--- a/libs/langchain_v1/tests/unit_tests/agents/middleware/implementations/test_model_retry.py
+++ b/libs/langchain_v1/tests/unit_tests/agents/middleware/implementations/test_model_retry.py
@@ -6,6 +6,10 @@ from typing import Any
import pytest
from langchain_core.callbacks import CallbackManagerForLLMRun
+from langchain_core.exceptions import (
+ ModelAuthenticationError,
+ ModelRateLimitError,
+)
from langchain_core.messages import AIMessage, BaseMessage, HumanMessage
from langchain_core.outputs import ChatGeneration, ChatResult
from langgraph.checkpoint.memory import InMemorySaver
@@ -68,6 +72,7 @@ class AlwaysFailingModel(FakeToolCallingModel):
error_message: str = Field(default="Model error")
error_type: type[Exception] = Field(default=ValueError)
+ attempts: int = Field(default=0)
@override
def _generate(
@@ -88,6 +93,7 @@ class AlwaysFailingModel(FakeToolCallingModel):
Raises:
Exception: Always raises the configured exception.
"""
+ self.attempts += 1
raise self.error_type(self.error_message)
@@ -321,6 +327,67 @@ def test_model_retry_non_retryable_exception_reraises() -> None:
)
+ "error_type",
+ [
+ # Retryable model errors use the full retry budget.
+ ModelRateLimitError,
+ # Exceptions the taxonomy does not classify keep retrying as before.
+ ValueError,
+ ],
+)
+def test_model_retry_retries_retryable_errors(error_type: type[Exception]) -> None:
+ """The default `retry_on` retries anything not marked non-retryable."""
+ model = AlwaysFailingModel(error_message="boom", error_type=error_type)
+ retry = ModelRetryMiddleware(
+ max_retries=2,
+ initial_delay=0,
+ jitter=False,
+ on_failure="continue",
+ )
+ agent = create_agent(
+ model=model,
+ tools=[],
+ middleware=[retry],
+ checkpointer=InMemorySaver(),
+ )
+
+ result = agent.invoke(
+ {"messages": [HumanMessage("Hello")]},
+ {"configurable": {"thread_id": "test"}},
+ )
+
+ assert model.attempts == 3
+ ai_messages = [m for m in result["messages"] if isinstance(m, AIMessage)]
+ assert "3 attempts" in ai_messages[-1].content
+
+
+def test_model_retry_reraises_non_retryable_model_error() -> None:
+ """Model errors marked non-retryable fail on the first attempt."""
+ model = AlwaysFailingModel(error_message="boom", error_type=ModelAuthenticationError)
+ retry = ModelRetryMiddleware(
+ max_retries=2,
+ initial_delay=0,
+ jitter=False,
+ on_failure="continue",
+ )
+ agent = create_agent(
+ model=model,
+ tools=[],
+ middleware=[retry],
+ checkpointer=InMemorySaver(),
+ )
+
+ # Unmatched exceptions propagate without going through `on_failure`.
+ with pytest.raises(ModelAuthenticationError):
+ agent.invoke(
+ {"messages": [HumanMessage("Hello")]},
+ {"configurable": {"thread_id": "test"}},
+ )
+
+ assert model.attempts == 1
+
+
def test_model_retry_custom_exception_filter() -> None:
"""Test ModelRetryMiddleware with custom exception filter function."""
diff --git a/libs/partners/anthropic/langchain_anthropic/chat_models.py b/libs/partners/anthropic/langchain_anthropic/chat_models.py
index 5b292975ab..5e01cdfe10 100644
--- a/libs/partners/anthropic/langchain_anthropic/chat_models.py
+++ b/libs/partners/anthropic/langchain_anthropic/chat_models.py
@@ -18,7 +18,18 @@ from langchain_core.callbacks import (
AsyncCallbackManagerForLLMRun,
CallbackManagerForLLMRun,
)
-from langchain_core.exceptions import ContextOverflowError, OutputParserException
+from langchain_core.exceptions import (
+ ContextOverflowError,
+ ModelAPIError,
+ ModelAuthenticationError,
+ ModelConnectionError,
+ ModelInvalidRequestError,
+ ModelNotFoundError,
+ ModelPermissionDeniedError,
+ ModelRateLimitError,
+ ModelTimeoutError,
+ OutputParserException,
+)
from langchain_core.language_models import (
LanguageModelInput,
ModelProfile,
@@ -910,6 +921,46 @@ class AnthropicContextOverflowError(anthropic.BadRequestError, ContextOverflowEr
"""BadRequestError raised when input exceeds Anthropic's context limit."""
+class AnthropicAuthenticationError(
+ anthropic.AuthenticationError, ModelAuthenticationError
+):
+ """Anthropic authentication error classified as a LangChain model error."""
+
+
+class AnthropicPermissionDeniedError(
+ anthropic.PermissionDeniedError, ModelPermissionDeniedError
+):
+ """Anthropic permission error classified as a LangChain model error."""
+
+
+class AnthropicInvalidRequestError(anthropic.BadRequestError, ModelInvalidRequestError):
+ """Anthropic bad-request error classified as a LangChain model error."""
+
+
+class AnthropicModelNotFoundError(anthropic.NotFoundError, ModelNotFoundError):
+ """Anthropic not-found error classified as a LangChain model error."""
+
+
+class AnthropicRateLimitError(anthropic.RateLimitError, ModelRateLimitError):
+ """Anthropic rate-limit error classified as a LangChain model error."""
+
+
+class AnthropicAPIError(anthropic.InternalServerError, ModelAPIError):
+ """Anthropic server error classified as a LangChain model error."""
+
+
+class AnthropicOverloadedError(anthropic.OverloadedError, ModelAPIError):
+ """Anthropic overloaded error (HTTP 529) classified as a LangChain model error."""
+
+
+class AnthropicConnectionError(anthropic.APIConnectionError, ModelConnectionError):
+ """Anthropic connection error classified as a LangChain model error."""
+
+
+class AnthropicTimeoutError(anthropic.APITimeoutError, ModelTimeoutError):
+ """Anthropic timeout error classified as a LangChain model error."""
+
+
def _raise_if_authentication_error(e: TypeError) -> None:
"""Re-raise anthropic SDK's missing-credentials `TypeError` with guidance."""
if "Could not resolve authentication method" in str(e):
@@ -933,7 +984,42 @@ def _handle_anthropic_bad_request(e: anthropic.BadRequestError) -> None:
if ("messages: at least one message is required") in e.message:
message = "Received only system message(s). "
warnings.warn(message, stacklevel=2)
- raise e
+ raise AnthropicInvalidRequestError(
+ message=e.message, response=e.response, body=e.body
+ ) from e
+
+
+def _handle_anthropic_api_error(e: anthropic.APIError) -> None:
+ """Re-raise an Anthropic SDK error as its LangChain-classified equivalent."""
+ if isinstance(e, anthropic.AuthenticationError):
+ raise AnthropicAuthenticationError(
+ message=e.message, response=e.response, body=e.body
+ ) from e
+ if isinstance(e, anthropic.PermissionDeniedError):
+ raise AnthropicPermissionDeniedError(
+ message=e.message, response=e.response, body=e.body
+ ) from e
+ if isinstance(e, anthropic.NotFoundError):
+ raise AnthropicModelNotFoundError(
+ message=e.message, response=e.response, body=e.body
+ ) from e
+ if isinstance(e, anthropic.RateLimitError):
+ raise AnthropicRateLimitError(
+ message=e.message, response=e.response, body=e.body
+ ) from e
+ if isinstance(e, anthropic.OverloadedError):
+ raise AnthropicOverloadedError(
+ message=e.message, response=e.response, body=e.body
+ ) from e
+ if isinstance(e, anthropic.InternalServerError):
+ raise AnthropicAPIError(
+ message=e.message, response=e.response, body=e.body
+ ) from e
+ # `APITimeoutError` subclasses `APIConnectionError`, so check it first.
+ if isinstance(e, anthropic.APITimeoutError):
+ raise AnthropicTimeoutError(e.request) from e
+ if isinstance(e, anthropic.APIConnectionError):
+ raise AnthropicConnectionError(message=e.message, request=e.request) from e
raise
@@ -1681,6 +1767,8 @@ class ChatAnthropic(BaseChatModel):
yield chunk
except anthropic.BadRequestError as e:
_handle_anthropic_bad_request(e)
+ except anthropic.APIError as e:
+ _handle_anthropic_api_error(e)
async def _astream(
self,
@@ -1718,6 +1806,8 @@ class ChatAnthropic(BaseChatModel):
yield chunk
except anthropic.BadRequestError as e:
_handle_anthropic_bad_request(e)
+ except anthropic.APIError as e:
+ _handle_anthropic_api_error(e)
def _make_message_chunk_from_anthropic_event(
self,
@@ -2011,6 +2101,8 @@ class ChatAnthropic(BaseChatModel):
data = self._create(payload)
except anthropic.BadRequestError as e:
_handle_anthropic_bad_request(e)
+ except anthropic.APIError as e:
+ _handle_anthropic_api_error(e)
return self._format_output(data, **kwargs)
async def _agenerate(
@@ -2025,6 +2117,8 @@ class ChatAnthropic(BaseChatModel):
data = await self._acreate(payload)
except anthropic.BadRequestError as e:
_handle_anthropic_bad_request(e)
+ except anthropic.APIError as e:
+ _handle_anthropic_api_error(e)
return self._format_output(data, **kwargs)
def _get_llm_for_structured_output_when_thinking_is_enabled(
diff --git a/libs/partners/anthropic/tests/unit_tests/test_chat_models.py b/libs/partners/anthropic/tests/unit_tests/test_chat_models.py
index f618eee60b..e7fa2aa762 100644
--- a/libs/partners/anthropic/tests/unit_tests/test_chat_models.py
+++ b/libs/partners/anthropic/tests/unit_tests/test_chat_models.py
@@ -11,10 +11,22 @@ from typing import Any, Literal, cast
from unittest.mock import MagicMock, patch
import anthropic
+import httpx
import pytest
from anthropic.types import Message, TextBlock, Usage
from blockbuster import blockbuster_ctx
-from langchain_core.exceptions import ContextOverflowError
+from langchain_core.exceptions import (
+ ContextOverflowError,
+ ModelAPIError,
+ ModelAuthenticationError,
+ ModelConnectionError,
+ ModelError,
+ ModelInvalidRequestError,
+ ModelNotFoundError,
+ ModelPermissionDeniedError,
+ ModelRateLimitError,
+ ModelTimeoutError,
+)
from langchain_core.messages import (
AIMessage,
AIMessageChunk,
@@ -4042,6 +4054,64 @@ _CONTEXT_OVERFLOW_BAD_REQUEST_ERROR = anthropic.BadRequestError(
)
+ ("status_code", "sdk_error_type", "model_error_type", "is_retryable"),
+ [
+ (400, anthropic.BadRequestError, ModelInvalidRequestError, False),
+ (401, anthropic.AuthenticationError, ModelAuthenticationError, False),
+ (403, anthropic.PermissionDeniedError, ModelPermissionDeniedError, False),
+ (404, anthropic.NotFoundError, ModelNotFoundError, False),
+ (429, anthropic.RateLimitError, ModelRateLimitError, True),
+ (500, anthropic.InternalServerError, ModelAPIError, True),
+ (529, anthropic.OverloadedError, ModelAPIError, True),
+ ],
+)
+def test_anthropic_error_classification(
+ status_code: int,
+ sdk_error_type: type[anthropic.APIStatusError],
+ model_error_type: type[ModelError],
+ *,
+ is_retryable: bool,
+) -> None:
+ """Provider errors are raised as both the SDK type and the LangChain type."""
+ llm = ChatAnthropic(model=MODEL_NAME)
+ sdk_error = sdk_error_type(
+ "model request failed",
+ response=MagicMock(status_code=status_code),
+ body=None,
+ )
+
+ with ( # noqa: PT012
+ patch.object(llm._client.messages, "create") as mock_create,
+ pytest.raises(sdk_error_type) as exc_info,
+ ):
+ mock_create.side_effect = sdk_error
+ llm.invoke([HumanMessage(content="test")])
+
+ assert isinstance(exc_info.value, model_error_type)
+ assert exc_info.value.is_retryable is is_retryable
+
+
+def test_anthropic_transport_error_classification() -> None:
+ """Timeout and connection failures are classified without a status code."""
+ llm = ChatAnthropic(model=MODEL_NAME)
+ request = httpx.Request("POST", "https://api.anthropic.com/v1/messages")
+
+ for sdk_error, model_error_type in (
+ (anthropic.APITimeoutError(request), ModelTimeoutError),
+ (anthropic.APIConnectionError(request=request), ModelConnectionError),
+ ):
+ with ( # noqa: PT012
+ patch.object(llm._client.messages, "create") as mock_create,
+ pytest.raises(type(sdk_error)) as exc_info,
+ ):
+ mock_create.side_effect = sdk_error
+ llm.invoke([HumanMessage(content="test")])
+
+ assert isinstance(exc_info.value, model_error_type)
+ assert exc_info.value.is_retryable is True
+
+
def test_context_overflow_error_invoke_sync() -> None:
"""Test context overflow error on invoke (sync)."""
llm = ChatAnthropic(model=MODEL_NAME)
diff --git a/libs/partners/fireworks/langchain_fireworks/chat_models.py b/libs/partners/fireworks/langchain_fireworks/chat_models.py
index 42b8f15513..22a34bec14 100644
--- a/libs/partners/fireworks/langchain_fireworks/chat_models.py
+++ b/libs/partners/fireworks/langchain_fireworks/chat_models.py
@@ -18,18 +18,33 @@ from typing import (
import httpx
from fireworks import (
APIConnectionError,
+ APIError,
+ APITimeoutError,
AsyncFireworks,
+ AuthenticationError,
BadRequestError,
Fireworks,
FireworksError,
InternalServerError,
+ NotFoundError,
+ PermissionDeniedError,
RateLimitError,
)
from langchain_core.callbacks import (
AsyncCallbackManagerForLLMRun,
CallbackManagerForLLMRun,
)
-from langchain_core.exceptions import ContextOverflowError
+from langchain_core.exceptions import (
+ ContextOverflowError,
+ ModelAPIError,
+ ModelAuthenticationError,
+ ModelConnectionError,
+ ModelInvalidRequestError,
+ ModelNotFoundError,
+ ModelPermissionDeniedError,
+ ModelRateLimitError,
+ ModelTimeoutError,
+)
from langchain_core.language_models import (
LanguageModelInput,
ModelProfile,
@@ -565,12 +580,70 @@ class FireworksContextOverflowError(BadRequestError, ContextOverflowError):
"""`BadRequestError` raised when input exceeds Fireworks's context limit."""
+class FireworksAuthenticationError(AuthenticationError, ModelAuthenticationError):
+ """Fireworks authentication error classified as a LangChain model error."""
+
+
+class FireworksPermissionDeniedError(PermissionDeniedError, ModelPermissionDeniedError):
+ """Fireworks permission error classified as a LangChain model error."""
+
+
+class FireworksInvalidRequestError(BadRequestError, ModelInvalidRequestError):
+ """Fireworks bad-request error classified as a LangChain model error."""
+
+
+class FireworksModelNotFoundError(NotFoundError, ModelNotFoundError):
+ """Fireworks not-found error classified as a LangChain model error."""
+
+
+class FireworksRateLimitError(RateLimitError, ModelRateLimitError):
+ """Fireworks rate-limit error classified as a LangChain model error."""
+
+
+class FireworksAPIError(InternalServerError, ModelAPIError):
+ """Fireworks server error classified as a LangChain model error."""
+
+
+class FireworksConnectionError(APIConnectionError, ModelConnectionError):
+ """Fireworks connection error classified as a LangChain model error."""
+
+
+class FireworksTimeoutError(APITimeoutError, ModelTimeoutError):
+ """Fireworks timeout error classified as a LangChain model error."""
+
+
def _handle_fireworks_invalid_request(e: BadRequestError) -> NoReturn:
"""Promote prompt-too-long errors to `FireworksContextOverflowError`."""
if "prompt is too long" in str(e):
raise FireworksContextOverflowError(
str(e), response=e.response, body=e.body
) from e
+ raise FireworksInvalidRequestError(str(e), response=e.response, body=e.body) from e
+
+
+def _handle_fireworks_api_error(e: APIError) -> NoReturn:
+ """Re-raise a Fireworks SDK error as its LangChain-classified equivalent."""
+ if isinstance(e, AuthenticationError):
+ raise FireworksAuthenticationError(
+ str(e), response=e.response, body=e.body
+ ) from e
+ if isinstance(e, PermissionDeniedError):
+ raise FireworksPermissionDeniedError(
+ str(e), response=e.response, body=e.body
+ ) from e
+ if isinstance(e, NotFoundError):
+ raise FireworksModelNotFoundError(
+ str(e), response=e.response, body=e.body
+ ) from e
+ if isinstance(e, RateLimitError):
+ raise FireworksRateLimitError(str(e), response=e.response, body=e.body) from e
+ if isinstance(e, InternalServerError):
+ raise FireworksAPIError(str(e), response=e.response, body=e.body) from e
+ # `APITimeoutError` subclasses `APIConnectionError`, so check it first.
+ if isinstance(e, APITimeoutError):
+ raise FireworksTimeoutError(e.request) from e
+ if isinstance(e, APIConnectionError):
+ raise FireworksConnectionError(message=str(e), request=e.request) from e
raise e
@@ -1090,6 +1163,8 @@ class ChatFireworks(BaseChatModel):
)
except BadRequestError as e:
_handle_fireworks_invalid_request(e)
+ except APIError as e:
+ _handle_fireworks_api_error(e)
for chunk in stream:
if not isinstance(chunk, dict):
chunk = chunk.model_dump()
@@ -1142,6 +1217,8 @@ class ChatFireworks(BaseChatModel):
)
except BadRequestError as e:
_handle_fireworks_invalid_request(e)
+ except APIError as e:
+ _handle_fireworks_api_error(e)
return self._create_chat_result(response)
def _create_message_dicts(
@@ -1203,6 +1280,8 @@ class ChatFireworks(BaseChatModel):
)
except BadRequestError as e:
_handle_fireworks_invalid_request(e)
+ except APIError as e:
+ _handle_fireworks_api_error(e)
async for chunk in stream:
if not isinstance(chunk, dict):
chunk = chunk.model_dump()
@@ -1258,6 +1337,8 @@ class ChatFireworks(BaseChatModel):
)
except BadRequestError as e:
_handle_fireworks_invalid_request(e)
+ except APIError as e:
+ _handle_fireworks_api_error(e)
return self._create_chat_result(response)
@property
diff --git a/libs/partners/fireworks/tests/unit_tests/test_chat_models.py b/libs/partners/fireworks/tests/unit_tests/test_chat_models.py
index 35263d1407..b4587fb78c 100644
--- a/libs/partners/fireworks/tests/unit_tests/test_chat_models.py
+++ b/libs/partners/fireworks/tests/unit_tests/test_chat_models.py
@@ -10,13 +10,28 @@ from unittest.mock import MagicMock
import httpx
import pytest
from fireworks import (
+ APIConnectionError,
+ APITimeoutError,
AuthenticationError,
BadRequestError,
FireworksError,
InternalServerError,
+ NotFoundError,
+ PermissionDeniedError,
RateLimitError,
)
-from langchain_core.exceptions import ContextOverflowError
+from langchain_core.exceptions import (
+ ContextOverflowError,
+ ModelAPIError,
+ ModelAuthenticationError,
+ ModelConnectionError,
+ ModelError,
+ ModelInvalidRequestError,
+ ModelNotFoundError,
+ ModelPermissionDeniedError,
+ ModelRateLimitError,
+ ModelTimeoutError,
+)
from langchain_core.messages import (
AIMessage,
AIMessageChunk,
@@ -1790,6 +1805,59 @@ _CONTEXT_OVERFLOW_MESSAGE = (
)
+ ("status_code", "sdk_error_type", "model_error_type", "is_retryable"),
+ [
+ (400, BadRequestError, ModelInvalidRequestError, False),
+ (401, AuthenticationError, ModelAuthenticationError, False),
+ (403, PermissionDeniedError, ModelPermissionDeniedError, False),
+ (404, NotFoundError, ModelNotFoundError, False),
+ (429, RateLimitError, ModelRateLimitError, True),
+ (500, InternalServerError, ModelAPIError, True),
+ ],
+)
+def test_fireworks_error_classification(
+ status_code: int,
+ sdk_error_type: type[Exception],
+ model_error_type: type[ModelError],
+ *,
+ is_retryable: bool,
+) -> None:
+ """Provider errors are raised as both the SDK type and the LangChain type."""
+ llm = _make_llm(max_retries=0)
+ mock_client = MagicMock()
+ mock_client.create.side_effect = _api_error(
+ sdk_error_type, "model request failed", status_code
+ )
+ llm.client = mock_client
+
+ with pytest.raises(sdk_error_type) as exc_info:
+ llm.invoke([HumanMessage(content="test")])
+
+ assert isinstance(exc_info.value, model_error_type)
+ assert exc_info.value.is_retryable is is_retryable
+
+
+def test_fireworks_transport_error_classification() -> None:
+ """Timeout and connection failures are classified without a status code."""
+ request = httpx.Request("POST", "https://api.fireworks.ai/inference/v1")
+
+ for sdk_error, model_error_type in (
+ (APITimeoutError(request), ModelTimeoutError),
+ (APIConnectionError(request=request), ModelConnectionError),
+ ):
+ llm = _make_llm(max_retries=0)
+ mock_client = MagicMock()
+ mock_client.create.side_effect = sdk_error
+ llm.client = mock_client
+
+ with pytest.raises(type(sdk_error)) as exc_info:
+ llm.invoke([HumanMessage(content="test")])
+
+ assert isinstance(exc_info.value, model_error_type)
+ assert exc_info.value.is_retryable is True
+
+
def test_context_overflow_error_invoke_sync() -> None:
"""Prompt-too-long errors surface as `ContextOverflowError` on invoke."""
llm = _make_llm(max_retries=0)
diff --git a/libs/partners/mistralai/langchain_mistralai/chat_models.py b/libs/partners/mistralai/langchain_mistralai/chat_models.py
index ef335674b1..e5415aef0b 100644
--- a/libs/partners/mistralai/langchain_mistralai/chat_models.py
+++ b/libs/partners/mistralai/langchain_mistralai/chat_models.py
@@ -23,6 +23,14 @@ from langchain_core.callbacks import (
AsyncCallbackManagerForLLMRun,
CallbackManagerForLLMRun,
)
+from langchain_core.exceptions import (
+ ModelAPIError,
+ ModelAuthenticationError,
+ ModelInvalidRequestError,
+ ModelNotFoundError,
+ ModelPermissionDeniedError,
+ ModelRateLimitError,
+)
from langchain_core.language_models import (
LanguageModelInput,
ModelProfile,
@@ -219,6 +227,58 @@ def _convert_mistral_chat_message_to_message(
)
+class MistralAIAuthenticationError(httpx.HTTPStatusError, ModelAuthenticationError):
+ """Mistral AI authentication error classified as a LangChain model error."""
+
+
+class MistralAIPermissionDeniedError(httpx.HTTPStatusError, ModelPermissionDeniedError):
+ """Mistral AI permission error classified as a LangChain model error."""
+
+
+class MistralAIInvalidRequestError(httpx.HTTPStatusError, ModelInvalidRequestError):
+ """Mistral AI invalid-request error classified as a LangChain model error."""
+
+
+class MistralAIModelNotFoundError(httpx.HTTPStatusError, ModelNotFoundError):
+ """Mistral AI not-found error classified as a LangChain model error."""
+
+
+class MistralAIRateLimitError(httpx.HTTPStatusError, ModelRateLimitError):
+ """Mistral AI rate-limit error classified as a LangChain model error."""
+
+
+class MistralAIAPIError(httpx.HTTPStatusError, ModelAPIError):
+ """Mistral AI server error classified as a LangChain model error."""
+
+
+_STATUS_ERROR_TYPES: dict[int, type[httpx.HTTPStatusError]] = {
+ 400: MistralAIInvalidRequestError,
+ 401: MistralAIAuthenticationError,
+ 403: MistralAIPermissionDeniedError,
+ 404: MistralAIModelNotFoundError,
+ 422: MistralAIInvalidRequestError,
+ 429: MistralAIRateLimitError,
+}
+"""HTTP status codes the Mistral AI API reports, keyed to LangChain error types."""
+
+
+def _status_error_type(status_code: int) -> type[httpx.HTTPStatusError]:
+ """Return the error type to raise for an HTTP status code.
+
+ Args:
+ status_code: The HTTP status code of the error response.
+
+ Returns:
+ The classified error type, or plain `httpx.HTTPStatusError` for status codes
+ the taxonomy does not cover.
+ """
+ if error_type := _STATUS_ERROR_TYPES.get(status_code):
+ return error_type
+ if status_code >= 500:
+ return MistralAIAPIError
+ return httpx.HTTPStatusError
+
+
def _raise_on_error(response: httpx.Response) -> None:
"""Raise an error if the response is an error."""
if httpx.codes.is_error(response.status_code):
@@ -227,7 +287,7 @@ def _raise_on_error(response: httpx.Response) -> None:
f"Error response {response.status_code} "
f"while fetching {response.url}: {error_message}"
)
- raise httpx.HTTPStatusError(
+ raise _status_error_type(response.status_code)(
msg,
request=response.request,
response=response,
@@ -242,7 +302,7 @@ async def _araise_on_error(response: httpx.Response) -> None:
f"Error response {response.status_code} "
f"while fetching {response.url}: {error_message}"
)
- raise httpx.HTTPStatusError(
+ raise _status_error_type(response.status_code)(
msg,
request=response.request,
response=response,
diff --git a/libs/partners/mistralai/tests/unit_tests/test_chat_models.py b/libs/partners/mistralai/tests/unit_tests/test_chat_models.py
index ade2a4a487..17c89b2cbf 100644
--- a/libs/partners/mistralai/tests/unit_tests/test_chat_models.py
+++ b/libs/partners/mistralai/tests/unit_tests/test_chat_models.py
@@ -8,6 +8,15 @@ from unittest.mock import MagicMock, patch
import httpx
import pytest
from langchain_core.callbacks.base import BaseCallbackHandler
+from langchain_core.exceptions import (
+ ModelAPIError,
+ ModelAuthenticationError,
+ ModelError,
+ ModelInvalidRequestError,
+ ModelNotFoundError,
+ ModelPermissionDeniedError,
+ ModelRateLimitError,
+)
from langchain_core.messages import (
AIMessage,
AIMessageChunk,
@@ -27,18 +36,26 @@ if TYPE_CHECKING:
from langchain_mistralai._compat import _convert_to_v1_from_mistral
from langchain_mistralai.chat_models import ( # type: ignore[import]
ChatMistralAI,
+ _araise_on_error,
_convert_chunk_to_message_chunk,
_convert_message_to_mistral_chat_message,
_convert_mistral_chat_message_to_message,
_convert_tool_call_id_to_mistral_compatible,
_format_message_content,
_is_valid_mistral_tool_call_id,
+ _raise_on_error,
_sanitize_chat_completions_content,
)
os.environ["MISTRAL_API_KEY"] = "foo"
+def _error_response(status_code: int) -> httpx.Response:
+ """Build a response with the given status for the error handlers."""
+ request = httpx.Request("POST", "https://api.mistral.ai/v1/chat/completions")
+ return httpx.Response(status_code, request=request, content=b'{"message": "boom"}')
+
+
def test_sanitize_chat_completions_text_blocks_strips_id() -> None:
"""LangChain auto-generated `id` on text blocks must not reach the wire.
@@ -1094,3 +1111,54 @@ def test_metadata_versions() -> None:
versions = llm.metadata["lc_versions"]
assert "langchain-core" in versions
assert "langchain-mistralai" in versions
+
+
+ ("status_code", "model_error_type", "is_retryable"),
+ [
+ (400, ModelInvalidRequestError, False),
+ (401, ModelAuthenticationError, False),
+ (403, ModelPermissionDeniedError, False),
+ (404, ModelNotFoundError, False),
+ (422, ModelInvalidRequestError, False),
+ (429, ModelRateLimitError, True),
+ (500, ModelAPIError, True),
+ (503, ModelAPIError, True),
+ ],
+)
+def test_error_classification(
+ status_code: int,
+ model_error_type: type[ModelError],
+ *,
+ is_retryable: bool,
+) -> None:
+ """Errors are raised as both `httpx.HTTPStatusError` and the LangChain type."""
+ response = _error_response(status_code)
+
+ with pytest.raises(httpx.HTTPStatusError) as exc_info:
+ _raise_on_error(response)
+
+ assert isinstance(exc_info.value, model_error_type)
+ assert exc_info.value.is_retryable is is_retryable
+ assert exc_info.value.response.status_code == status_code
+
+
+async def test_error_classification_async() -> None:
+ """The async response handler classifies errors the same way."""
+ with pytest.raises(httpx.HTTPStatusError) as exc_info:
+ await _araise_on_error(_error_response(429))
+
+ assert isinstance(exc_info.value, ModelRateLimitError)
+
+
+def test_unclassified_status_stays_a_plain_status_error() -> None:
+ """Status codes outside the taxonomy keep the previous behavior."""
+ with pytest.raises(httpx.HTTPStatusError) as exc_info:
+ _raise_on_error(_error_response(409))
+
+ assert not isinstance(exc_info.value, ModelError)
+
+
+def test_success_response_does_not_raise() -> None:
+ """A non-error response is left alone."""
+ _raise_on_error(_error_response(200))
diff --git a/libs/partners/openai/langchain_openai/chat_models/base.py b/libs/partners/openai/langchain_openai/chat_models/base.py
index 692b61333f..05341ac3d1 100644
--- a/libs/partners/openai/langchain_openai/chat_models/base.py
+++ b/libs/partners/openai/langchain_openai/chat_models/base.py
@@ -51,7 +51,17 @@ from langchain_core.callbacks import (
AsyncCallbackManagerForLLMRun,
CallbackManagerForLLMRun,
)
-from langchain_core.exceptions import ContextOverflowError
+from langchain_core.exceptions import (
+ ContextOverflowError,
+ ModelAPIError,
+ ModelAuthenticationError,
+ ModelConnectionError,
+ ModelInvalidRequestError,
+ ModelNotFoundError,
+ ModelPermissionDeniedError,
+ ModelRateLimitError,
+ ModelTimeoutError,
+)
from langchain_core.language_models import (
LanguageModelInput,
ModelProfileRegistry,
@@ -563,6 +573,40 @@ class OpenAIAPIContextOverflowError(openai.APIError, ContextOverflowError):
"""APIError raised when input exceeds OpenAI's context limit."""
+class OpenAIAuthenticationError(openai.AuthenticationError, ModelAuthenticationError):
+ """OpenAI authentication error classified as a LangChain model error."""
+
+
+class OpenAIPermissionDeniedError(
+ openai.PermissionDeniedError, ModelPermissionDeniedError
+):
+ """OpenAI permission error classified as a LangChain model error."""
+
+
+class OpenAIInvalidRequestError(openai.BadRequestError, ModelInvalidRequestError):
+ """OpenAI bad-request error classified as a LangChain model error."""
+
+
+class OpenAIModelNotFoundError(openai.NotFoundError, ModelNotFoundError):
+ """OpenAI not-found error classified as a LangChain model error."""
+
+
+class OpenAIRateLimitError(openai.RateLimitError, ModelRateLimitError):
+ """OpenAI rate-limit error classified as a LangChain model error."""
+
+
+class OpenAIAPIError(openai.InternalServerError, ModelAPIError):
+ """OpenAI server error classified as a LangChain model error."""
+
+
+class OpenAIConnectionError(openai.APIConnectionError, ModelConnectionError):
+ """OpenAI connection error classified as a LangChain model error."""
+
+
+class OpenAITimeoutError(openai.APITimeoutError, ModelTimeoutError):
+ """OpenAI timeout error classified as a LangChain model error."""
+
+
def _handle_openai_bad_request(e: openai.BadRequestError) -> None:
if (
"context_length_exceeded" in str(e)
@@ -583,7 +627,9 @@ def _handle_openai_bad_request(e: openai.BadRequestError) -> None:
'specify `method="function_calling"`.'
)
warnings.warn(message)
- raise e
+ raise OpenAIInvalidRequestError(
+ message=e.message, response=e.response, body=e.body
+ ) from e
if "Invalid schema for response_format" in e.message:
message = (
"Invalid schema for OpenAI's structured output feature, which is the "
@@ -593,8 +639,9 @@ def _handle_openai_bad_request(e: openai.BadRequestError) -> None:
"https://platform.openai.com/docs/guides/structured-outputs#supported-schemas"
)
warnings.warn(message)
- raise e
- raise
+ raise OpenAIInvalidRequestError(
+ message=e.message, response=e.response, body=e.body
+ ) from e
def _handle_openai_api_error(e: openai.APIError) -> None:
@@ -603,6 +650,28 @@ def _handle_openai_api_error(e: openai.APIError) -> None:
raise OpenAIAPIContextOverflowError(
message=e.message, request=e.request, body=e.body
) from e
+ if isinstance(e, openai.AuthenticationError):
+ raise OpenAIAuthenticationError(
+ message=e.message, response=e.response, body=e.body
+ ) from e
+ if isinstance(e, openai.PermissionDeniedError):
+ raise OpenAIPermissionDeniedError(
+ message=e.message, response=e.response, body=e.body
+ ) from e
+ if isinstance(e, openai.NotFoundError):
+ raise OpenAIModelNotFoundError(
+ message=e.message, response=e.response, body=e.body
+ ) from e
+ if isinstance(e, openai.RateLimitError):
+ raise OpenAIRateLimitError(
+ message=e.message, response=e.response, body=e.body
+ ) from e
+ if isinstance(e, openai.InternalServerError):
+ raise OpenAIAPIError(message=e.message, response=e.response, body=e.body) from e
+ if isinstance(e, openai.APITimeoutError):
+ raise OpenAITimeoutError(e.request) from e
+ if isinstance(e, openai.APIConnectionError):
+ raise OpenAIConnectionError(message=e.message, request=e.request) from e
raise
diff --git a/libs/partners/openai/tests/unit_tests/chat_models/test_base.py b/libs/partners/openai/tests/unit_tests/chat_models/test_base.py
index 23db43147c..6ac9337648 100644
--- a/libs/partners/openai/tests/unit_tests/chat_models/test_base.py
+++ b/libs/partners/openai/tests/unit_tests/chat_models/test_base.py
@@ -13,7 +13,18 @@ import httpx
import httpx2
import openai
import pytest
-from langchain_core.exceptions import ContextOverflowError
+from langchain_core.exceptions import (
+ ContextOverflowError,
+ ModelAPIError,
+ ModelAuthenticationError,
+ ModelConnectionError,
+ ModelError,
+ ModelInvalidRequestError,
+ ModelNotFoundError,
+ ModelPermissionDeniedError,
+ ModelRateLimitError,
+ ModelTimeoutError,
+)
from langchain_core.load import dumps, loads
from langchain_core.messages import (
AIMessage,
@@ -4857,6 +4868,57 @@ def test_context_overflow_error_backwards_compatibility() -> None:
assert isinstance(exc_info.value, ContextOverflowError)
+ ("status_code", "sdk_error_type", "model_error_type", "is_retryable"),
+ [
+ (400, openai.BadRequestError, ModelInvalidRequestError, False),
+ (401, openai.AuthenticationError, ModelAuthenticationError, False),
+ (403, openai.PermissionDeniedError, ModelPermissionDeniedError, False),
+ (404, openai.NotFoundError, ModelNotFoundError, False),
+ (429, openai.RateLimitError, ModelRateLimitError, True),
+ (500, openai.InternalServerError, ModelAPIError, True),
+ ],
+)
+def test_openai_error_classification(
+ status_code: int,
+ sdk_error_type: type[openai.APIStatusError],
+ model_error_type: type[ModelError],
+ *,
+ is_retryable: bool,
+) -> None:
+ """Provider errors are raised as both the SDK type and the LangChain type."""
+ request = httpx2.Request("POST", "https://api.openai.com/v1/chat/completions")
+ response = httpx2.Response(status_code, request=request)
+ sdk_error = sdk_error_type("model request failed", response=response, body=None)
+ model = ChatOpenAI(api_key=SecretStr("test"))
+
+ with patch.object(model.client, "with_raw_response") as mock_client:
+ mock_client.create.side_effect = sdk_error
+ with pytest.raises(sdk_error_type) as exc_info:
+ model.invoke("test")
+
+ assert isinstance(exc_info.value, model_error_type)
+ assert exc_info.value.is_retryable is is_retryable
+
+
+def test_openai_transport_error_classification() -> None:
+ """Timeout and connection failures are classified without a status code."""
+ request = httpx2.Request("POST", "https://api.openai.com/v1/chat/completions")
+ model = ChatOpenAI(api_key=SecretStr("test"))
+
+ for sdk_error, model_error_type in (
+ (openai.APITimeoutError(request), ModelTimeoutError),
+ (openai.APIConnectionError(request=request), ModelConnectionError),
+ ):
+ with patch.object(model.client, "with_raw_response") as mock_client:
+ mock_client.create.side_effect = sdk_error
+ with pytest.raises(type(sdk_error)) as exc_info:
+ model.invoke("test")
+
+ assert isinstance(exc_info.value, model_error_type)
+ assert exc_info.value.is_retryable is True
+
+
def test_metadata_versions() -> None:
"""Test that metadata reports the correct version info."""
llm = ChatOpenAI()