anthropic-sdk-python v2.5.0: error handling and bedrock/vertex path fixes

We track SDK releases the same way we track CVEs for any dependency that touches production inference calls: who imports it, what changed in error semantics, and whether a client-side validation gap just got closed. The anthropic-sdk-python v2.5.0 release notes landed this week, and most of the diff is unglamorous: error class hierarchy tweaks, a handful of path-encoding bug fixes for Bedrock and Vertex, a thread-safety fix on first model parse. None of it is a breaking-change headline. All of it is the kind of thing that bites you three months from now if your retry logic or your exception handling assumed the old behavior.

Source: anthropic-sdk-python v2.5.0 release notes.

What actually changed

The feature list is short and API-surface-focused:

• New error details types and new error type values on the API side.
• An ids filter added to the list-workspaces endpoint.
• New error classes keyed to HTTP statuses and API error codes, plus error_code, details, and api_message attributes added to APIStatusError.

The bug fixes are where the operational risk sits:

• OverloadedError and ServiceUnavailableError are now subclasses of InternalServerError.
• The client now rejects path parameters like '..;x' and ';x', and rejects a None path parameter outright (there's a new test covering this).
• Bedrock: passing model as . or .. now raises a ValueError instead of silently routing the request to a different path. An empty model string now raises instead of hitting /model//invoke.
• Vertex: model, project ID, and region are now percent-encoded in the request path.
• The memory tool no longer allows renaming or deleting the /memories directory.
• The first parse of each response model is now thread-safe, and union validation on pydantic v1 is now correct across threads.

Everything else is docs and internal chores: clarified field descriptions, reworded RBAC role permission text, changelog tooling, stale TODO cleanup.

Who this matters to

If your org calls Claude through the Python SDK in production agents, three teams should care, for different reasons:

Platform/engineering teams running Bedrock or Vertex integrations. The path-encoding and ValueError-on-bad-model fixes mean the client now fails fast and loud on malformed model identifiers instead of sending a request to an unintended path. If you have config-driven model selection (environment variables, feature flags, a database lookup that can return an empty string), you want to confirm your error handling catches ValueError at the call site rather than assuming the request always reaches the intended endpoint.

Teams with custom retry/backoff logic keyed on exception type. If you wrote retry logic that branches on isinstance(e, InternalServerError) versus catching OverloadedError or ServiceUnavailableError separately, the subclass relationship changed in this release. Code that only caught the specific subclasses and fell through to a generic handler for InternalServerError will now also catch overload and unavailability errors in that same branch. Worth a five-minute audit of any except block that enumerates these three names explicitly.

Security and detection teams instrumenting outbound AI calls. The path-parameter rejection ('..;x', ';x', None) is a client-side input validation hardening. If you have detection logic in Sentinel or another SIEM watching for anomalous outbound paths from your inference layer, that detection should now see fewer false negatives from malformed paths reaching the wire, because the SDK rejects them before the request is built. If you log SDK exceptions into your SIEM pipeline, confirm your parser handles the new error_code, details, and api_message fields on APIStatusError rather than dropping them as unrecognized attributes.

What to check this week

Start with a version pin audit. If you're running agents or pipelines that depend on anthropic-sdk-python, check your lockfile:

pip show anthropic
grep -R "anthropic" requirements.txt pyproject.toml poetry.lock 2>/dev/null

Then grep your codebase for the three exception classes that changed hierarchy, so you know exactly where the subclass change has behavioral effect:

grep -RnE "OverloadedError|ServiceUnavailableError|InternalServerError" \
  --include="*.py" .

For Bedrock or Vertex users, grep for any place model identifiers are built dynamically rather than hardcoded, since that's where an empty string or a path-traversal-shaped value (. or ..) could have previously slipped through:

grep -RnE "model\s*=\s*(os\.environ|config\.|get\()" --include="*.py" .

If you catch APIStatusError anywhere and only read .status_code or .message, add handling for the new .error_code, .details, and .api_message attributes so you're not silently discarding diagnostic data the API is now sending you.

from anthropic import APIStatusError

try:
    response = client.messages.create(...)
except APIStatusError as e:
    log.error(
        "anthropic_api_error",
        status_code=e.status_code,
        error_code=getattr(e, "error_code", None),
        api_message=getattr(e, "api_message", None),
        details=getattr(e, "details", None),
    )
    raise

Use getattr with a default rather than direct attribute access until you've confirmed your pinned version actually includes these fields; mixing SDK versions across services is common enough in larger orgs that defensive access costs nothing.

What we are not claiming

The release notes don't describe this as a security advisory, and we're not treating it as one. The path-rejection and percent-encoding fixes read as defensive hardening against malformed or adversarial input reaching Bedrock and Vertex request construction, not as confirmation of an exploited vulnerability. We'd rather state that plainly than imply a CVE that isn't in the source. If you want the authoritative read, go straight to the release notes on GitHub rather than any secondhand summary, including this one.

Where this fits in a bigger pattern

None of this is dramatic on its own. But SDK-level input validation fixes are exactly the category of change that detection engineering teams should be feeding into their asset inventory and dependency-monitoring workflows, the same way you'd track a patched library in any other service. If your AI agent stack spans multiple clouds, through Bedrock, Vertex, and direct API calls, keeping SDK versions synchronized and your exception handling current across all three paths is table-stakes operational hygiene, not a nice-to-have.

We build and harden exactly this kind of multi-cloud agent infrastructure, from model routing logic to the SIEM detections that watch it. See our AI agents practice for how we approach it.

Next steps

If you want a second set of eyes on your SDK version pins, retry logic, or exception handling before this kind of release bites you in production, get in touch.