fix(models): wrap Anthropic rate limit errors

Merge #5401

## Summary
- wrap Anthropic RateLimitError in a dedicated ADK exception with mitigation guidance
- apply the wrapper consistently for both streaming and non-streaming Claude requests
- add regression tests for both code paths

## Testing
- python3 -m py_compile src/google/adk/models/anthropic_llm.py tests/unittests/models/test_anthropic_llm.py
- python3 -m pytest tests/unittests/models/test_anthropic_llm.py -k "wraps_anthropic_rate_limit_error" *(fails in this environment because the pytest interpreter is missing the  package during collection)*

Co-authored-by: George Weale <gweale@google.com>
COPYBARA_INTEGRATE_REVIEW=#5401 from MukundaKatta:codex/adk-anthropic-rate-limit e08c51b
PiperOrigin-RevId: 956692885

Author: 2 people

src/google/adk/models/anthropic_llm.py

@@ -37,6 +37,7 @@
 from anthropic import AsyncAnthropicVertex
 from anthropic import NOT_GIVEN
 from anthropic import NotGiven
+from anthropic import RateLimitError
 from anthropic import types as anthropic_types
 from google.genai import types
 from pydantic import BaseModel
@@ -57,6 +58,28 @@
 logger = logging.getLogger("google_adk." + __name__)
 
 
+_RATE_LIMIT_POSSIBLE_FIX_MESSAGE = (
+    "On how to mitigate this issue, please refer to:\n\n"
+    "https://docs.anthropic.com/en/api/errors#http-errors"
+)
+
+
+# anthropic is an optional dependency, so mypy resolves the base class to Any.
+class _AnthropicRateLimitError(RateLimitError):  # type: ignore[misc]
+  """Represents a rate limit error received from Anthropic."""
+
+  def __init__(self, rate_limit_error: RateLimitError):
+    super().__init__(
+        str(rate_limit_error),
+        response=rate_limit_error.response,
+        body=getattr(rate_limit_error, "body", None),
+    )
+
+  def __str__(self) -> str:
+    base_message = super().__str__()
+    return f"{_RATE_LIMIT_POSSIBLE_FIX_MESSAGE}\n\n{base_message}"
+
+
 @dataclasses.dataclass
 class _ToolUseAccumulator:
   """Accumulates streamed tool_use content block data."""
@@ -744,17 +767,20 @@ async def generate_content_async(
     )
     thinking = _build_anthropic_thinking_param(llm_request.config)
 
-    if not stream:
-      kwargs = self._build_anthropic_kwargs(
-          llm_request, messages, tools, tool_choice, thinking
-      )
-      message = await self._anthropic_client.messages.create(**kwargs)
-      yield message_to_generate_content_response(message)
-    else:
-      async for response in self._generate_content_streaming(
-          llm_request, messages, tools, tool_choice, thinking
-      ):
-        yield response
+    try:
+      if not stream:
+        kwargs = self._build_anthropic_kwargs(
+            llm_request, messages, tools, tool_choice, thinking
+        )
+        message = await self._anthropic_client.messages.create(**kwargs)
+        yield message_to_generate_content_response(message)
+      else:
+        async for response in self._generate_content_streaming(
+            llm_request, messages, tools, tool_choice, thinking
+        ):
+          yield response
+    except RateLimitError as rate_limit_error:
+      raise _AnthropicRateLimitError(rate_limit_error) from rate_limit_error
 
   async def _generate_content_streaming(
       self,

tests/unittests/models/test_anthropic_llm.py

@@ -22,10 +22,12 @@
 from unittest.mock import MagicMock
 
 from anthropic import NOT_GIVEN
+from anthropic import RateLimitError
 from anthropic import types as anthropic_types
 from google.adk import version as adk_version
 from google.adk.models import anthropic_llm
 from google.adk.models import AnthropicGenerateContentConfig
+from google.adk.models.anthropic_llm import _AnthropicRateLimitError
 from google.adk.models.anthropic_llm import AnthropicLlm
 from google.adk.models.anthropic_llm import Claude
 from google.adk.models.anthropic_llm import content_to_message_param
@@ -39,6 +41,7 @@
 from google.genai import version as genai_version
 from google.genai.types import Content
 from google.genai.types import Part
+import httpx
 import pytest
 
 
@@ -2802,3 +2805,55 @@ async def test_streaming_sets_finish_reason():
 
   final = responses[-1]
   assert final.finish_reason == types.FinishReason.MAX_TOKENS
+
+
+def _make_rate_limit_error() -> RateLimitError:
+  request = httpx.Request("POST", "https://api.anthropic.com/v1/messages")
+  response = httpx.Response(429, request=request)
+  return RateLimitError(
+      "rate limited",
+      response=response,
+      body={"type": "error", "error": {"type": "rate_limit_error"}},
+  )
+
+
+@pytest.mark.asyncio
+async def test_non_streaming_wraps_anthropic_rate_limit_error():
+  llm = AnthropicLlm(model="claude-sonnet-4-20250514")
+  mock_client = MagicMock()
+  mock_client.messages.create = AsyncMock(side_effect=_make_rate_limit_error())
+
+  llm_request = LlmRequest(
+      model="claude-sonnet-4-20250514",
+      contents=[Content(role="user", parts=[Part.from_text(text="Hi")])],
+      config=types.GenerateContentConfig(system_instruction="Test"),
+  )
+
+  with mock.patch.object(llm, "_anthropic_client", mock_client):
+    with pytest.raises(_AnthropicRateLimitError) as excinfo:
+      _ = [r async for r in llm.generate_content_async(llm_request)]
+
+  assert "docs.anthropic.com/en/api/errors#http-errors" in str(excinfo.value)
+  assert "rate limited" in str(excinfo.value)
+
+
+@pytest.mark.asyncio
+async def test_streaming_wraps_anthropic_rate_limit_error():
+  llm = AnthropicLlm(model="claude-sonnet-4-20250514")
+  mock_client = MagicMock()
+  mock_client.messages.create = AsyncMock(side_effect=_make_rate_limit_error())
+
+  llm_request = LlmRequest(
+      model="claude-sonnet-4-20250514",
+      contents=[Content(role="user", parts=[Part.from_text(text="Hi")])],
+      config=types.GenerateContentConfig(system_instruction="Test"),
+  )
+
+  with mock.patch.object(llm, "_anthropic_client", mock_client):
+    with pytest.raises(_AnthropicRateLimitError) as excinfo:
+      _ = [
+          r async for r in llm.generate_content_async(llm_request, stream=True)
+      ]
+
+  assert "docs.anthropic.com/en/api/errors#http-errors" in str(excinfo.value)
+  assert "rate limited" in str(excinfo.value)